Mnemonic uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the
2xx range indicate success. Codes in the
4xx range indicate an error that failed given the information provided (e.g., an invalid argument provided, a required parameter was missing, etc.). Codes in the
5xx range indicate an error with Mnemonic's servers, and are generally rare.
4xx errors can be handled programmatically and include additional useful information in the response that briefly explains the problem. For example, most common
400 which indicates an invalid argument that a client provided in the request will include additional message indicating an invalid argument ex.
token_id: value required.
Errors and codes uniformly apply to all REST and gRPC endpoints.
|200 - OK||Everything worked as expected.|
|400 - Bad Request||The request was unacceptable, often due to missing a required argument.|
|401 - Unauthorized||No valid API key provides.|
|404 - Not Found||The requested resource does not exist.|
|429 - Too Many Requests||Too many requests hit the API too quickly. We recommend exponential backoff of your requests and other strategies for mitigating this error.|
|500, 502, 503, 504 - Server Errors||Something went wrong on Mnemonic's end. We recommend retrying the request.|
While integrating with Mnemonic API you might have to deal with errors at some point when making requests. Most of the errors fall into these major categories:
- Resource errors – Invalid/non-existent resource requested or a body of the request is invalid.
- Network errors – Intermittent communication problems between client and server.
- Server errors – A problem with Mnemonic's servers.
Resource errors are the result of the contents of an API request being invalid or missing requested resource and return an HTTP response with a
4xx error code. For example, the API servers might return a
401 if an invalid API key was provided, or a
400 if a required parameter was missing. Clients should correct the original request, and try again.
Network errors are the result of connectivity problems between client and server and return low-level errors like socket or timeout exceptions. For example, a client might time out while trying to read from Mnemonic’s servers, or an API response might never be received because a connection terminates prematurely.
When intermittent problems occur, clients are usually left in a state where they don’t know whether or not the server received the request. Given that Mnemonic provides readonly API, the best strategy is to retry such requests with the same parameters until the client is able to receive a result from the server. When retrying requests make sure that the HTTP client that is being used to make requests supports exponential backoff, otherwise frequent retries over a short period of time may lead to another error indicating too many requests
Server errors are the result of a problem with Mnemonic's servers and return an HTTP response with a
5xx error code. These errors are the most difficult to handle and we work to make them as rare as possible—but integrations should be able to handle them when they do arise.
Clients should treat the
5xx reponse as indeterminate. The most likely time of such error occuring is during a production incident, and during such an incident remediation. We pro-actively observe such failed requests and try appropriately handle these incidents in the shortest time possible.
If a client starts observing such errors we recommend to retry after some reasonable delay.