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.
Some 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.
| Codes | Errors |
|---|---|
| 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. |
Error handling
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
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
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 429.
Server errors
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.