Skip to main content

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 codeextra fieldscausesummaryexample
400Wrong valueOne 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.
401UnauthorizedThe 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.
403ForbiddenThe access to an operation was denied, likely due it being currently not supported or active for the provided user.
404Entity not foundA requested entity or operation was not found on the system.Attempt to fetch batch information for a non-existent batch.
409Resource occupiedA requested operation handles a resource that is currently being used in another requested operation.Attempt to classify a transaction with a custom model that is being trained.
422ValidationThe 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.
429Too many requestsThe 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.
500Unexpected errorThe 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).


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 enrichemnt (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.