Results and errors
Structure
Results and errors are represented consistently in different parts of the API. The field name will always end in code, such as result_code or error_code. Different results are represented as string codes containing uppercase letters, numbers and underscores. They are an open-ended set, meaning that a comprehensive listing of every code is not available and new codes may be added in the future without versioning.
Result and error code field is often accompanied by a description field on the same level with a similar name, such as result_description or error_description. It is an English language description of the result or error that may give more details about the exact event than just the code. This additional description is meant to be used only for debugging and should not be translated or relied upon in any way for behaviour. The description contents may change at any time and may have dynamic parts.
The result code SUCCESS is different from the other codes in that it means absence of an error. It is not accompanied by description or details. Implementing software should expose this value appropriately, usually not as an error code but a separate return type. There will only ever be a single result code that means success, so implementing software can rely on SUCCESS being successful and every other code being an error/failure.
When error and result codes are read and propagated on the client side, they should be preserved as open-ended strings codes, meaning that even codes the software does not recognize get preserved verbatim. However, if it is not reasonable to use a string code to represent errors throughout the software, they may also be mapped to numbers and enumerations. A special code UNKNOWN is reserved to represent unrecognized error codes on the client side, ensuring that if these codes are sent back to the server, it is evident that the original error code was not preserved.
For any error detected by execution that isn’t mapped to a specific error code the code INTERNAL_ERROR should be used. This denotes an exception or other detected error in software where the error is unexpected and a more specific error code can’t be given. All INTERNAL_ERROR codes mean programming errors where a software fix should be made to fix them.
Common codes
SUCCESS (HTTP status 200)
Used to indicate that the operation was successful. Not an error code, which means that it will never be returned in errors, only in result_code field for transactions.
BAD_REQUEST (HTTP status 400)
Used to indicate that the request was not valid. This can be due to incorrect arguments, such as missing required fields or invalid values. It can also be triggered by configuration problems, such as a certain feature not being enabled. It is not usually beneficial to immediately retry a request that returns this error, as it is likely to fail again.
AUTHENTICATION_ERROR (HTTP status 401)
Used to indicate that the request was not authenticated. This can be due to missing or invalid authentication credentials. The request should not be repeated without correcting the authentication credentials.
AUTHORIZATION_ERROR (HTTP status 403)
Used to indicate that performing the operation was forbidden. This means that the request was authenticated, but the client does not have permission to perform the operation. This can be due to insufficient permissions or other restrictions. The request should not be repeated before resolving the permission issue.
NOT_FOUND (HTTP status 404)
Used to indicate that the requested resource was not found. The given identifiers in the request refer to a resource that was not found. The request should not be repeated without correcting the identifiers.
CONFLICT (HTTP status 409)
Used to indicate that the request conflicts with a previous request. This happens when multiple different operations use the same external identifier. Repeating a request with the same contents will not cause this error, as the operations are built to be idempotent. Getting this response code means a likely programming error. The request should not be repeated without correcting the identifiers.
TOO_MANY_REQUESTS (HTTP status 429)
Used to indicate that the client has sent too many requests in a given amount of time. This can be due to rate limiting or other restrictions. The server may return a Retry-After header with a suggested time to wait before retrying the request. The request should not be repeated without waiting for the suggested time.
INTERNAL_ERROR (HTTP status 500)
Used to indicate that an internal error occurred. Any unexpected error on the server side that is not mapped to a specific error code will be returned as INTERNAL_ERROR. These will also be flagged for investigation as they should not happen in normal operation. Repeating the request may or may not resolve the error.
UNKNOWN (HTTP status 500)
Used to indicate that an unknown error occurred. This is specifically used for any specific error codes that are not recognized and cannot be preserved intact. Usually the underlying error code will be present in the description of the error. Repeating the request may or may not resolve the error.
SERVICE_UNAVAILABLE (HTTP status 503)
Used to indicate that the server is unable to fulfill the request. This can be due to being overloaded or other issues. The server may return a Retry-After header with a suggested time to wait before retrying the request. The request should not be repeated without waiting for the suggested time.
ABORTED
Used to indicate that the operation was aborted. This can mean it was aborted by the client, or by the customer, or by some timeout during the operation. If the transaction is repeated, it should usually succeed as long as the new transaction is not aborted again. This error will only be seen as a result_code in the transaction, not as an error code.
REJECTED
Used to indicate that the operation was rejected. This means some step operation gave a rejection result, such as declined authorization. This can be due to a number of issues, some of which are transient and some of which are permanent. Retrying the transaction may or may not succeed, depending on the underlying reason for the rejection. This error will only be seen as a result_code in the transaction, not as an error code.
NETWORK_ERROR
Used to indicate that a network error occurred. This means network connectivity issues of some sort at some point in during the operation. The error can also be from the payment network, such as being unable to reach the issuing bank. Retrying the transaction may or may not succeed, depending on the underlying reason for the network error. This error will only be seen as a result_code in the transaction, not as an error code.
NOT_ACCEPTED
Used to indicate that the payment instrument is not accepted or valid for the operation. This can be due to a number of issues, such as a card being expired or from a payment scheme that is not supported by the terminal. Retrying the operation the same payment instrument is unlikely to succeed. This error will only be seen as a result_code in the transaction, not as an error code.