Error Handling
The Ntropy API uses HTTP status codes to signal errors in synchronous operations. In asynchronous operations, the errors are reported through error fields in the data structures returned when querying the state of the operation.
HTTP responses
The standard response in case of an error is to return an adequate HTTP status code, and a body containing a JSON structure that provides further information about the error. If the error response has a body, it contains a JSON dictionary with at least one key details, and a string value that provides a general description of the error. An error body may contain other fields with further information that are specific to that error.
In the next table, all the error codes currently in use in the API are listed.
| status code | extra fields | cause | summary | example |
|---|---|---|---|---|
| 400 | Wrong value | One or more of the provided values is not a valid value for the request. | Attempt to create an account holder with an id that already exists. | |
| 401 | Unauthorized | The user identified by the provided API key is not authorized for the requested operation. This error may occur if no API key is provided. | Attempt to enrich a transaction without providing an API key. | |
| 403 | Forbidden | The access to an operation was denied, likely due it being currently not supported or active for the provided user. | ||
| 404 | Entity not found | A requested entity or operation was not found on the system. | Attempt to fetch batch information for a non-existent batch. | |
| 422 | Validation | The provided body of the request does not match the expected input fields or data types. | Submit a request with a string value for a required integer value. | |
| 429 | Too many requests | The identified user has exceeded the allowed number of requests in a certain time interval (see Rate Limit section). If the header of the response does not contain a Retry-After, the user exceeded it's total quota of use and must reach out to Ntropy. | Sequence of requests in a short-time span that exceeds the defined rate limit for an operation. | |
| 500 | Unexpected error | The server failed with an unexpected or unhandled error. |
Asynchronous errors
All asynchronous operations that error follow the same pattern for error reporting: when fetching the state of the operation, the status field of the provided response will contain the value error. The returned response may contain other attributes that further describe the error, which vary from operation to operation and are described in the API reference per request.
SDK errors
The SDK will handle all of the expected errors (according to the table above), both synchronous and asynchronous, and wrap them in an ntropy_sdk.NtropyError that contains the previously described error information. Any unexpected error on the server side will be raised as a requests.HTTPError on the client side.
Handling these two errors on the client side will cover all of the possible server-side errors. However, there may be others errors raised, such as connection errors (i.e., requests.ConnectionError).
Enrichment
The API calls for enrichment (/v2/transactions/sync and /v2/transactions/async) have slightly different behaviours for error handling to provide more information to the user for each failed transaction.
If the enrichment failed for all transactions due to a service-level issue (i.e., downtime) or a problem understanding the request (i.e., 400 errors), no transaction batch will be created and information regarding the error is provided by the returned HTTP status code, both in the sync and async endpoints, with the semantic meaning described in the above table.
However, if the sync / async call succeeds, it is still possible for particular transactions to fail enrichment. When inspecting the results of an enrichment (the returned value of the sync call, or the transactions field of an async batch), the result list can contain both EnrichedTransaction or TransactionError objects (as named in the openapi specification that can be consulted in the API Reference page). The objects are returned in the same order as the input transactions; if a certain transaction returns a TransactionError, this object will contain more information on why the enrichment failed. This is handled in the SDK by raising an ntropy_sdk.errors.NtropyBatchError with information on the failed transactions.