Errors

Overview

Mono uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted etc.). Codes in the 5xx range indicate an error with our servers (these are rare).

Error 🚦	What
400 - Bad Request	The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized	No valid API key provided.
402 - Request Failed	The parameters were valid but the request failed.
403 - Forbidden	The API key doesn't have permissions to perform the request.
404 - Not Found	The requested resource doesn't exist.
409 - Conflict	The request conflicts with another request (perhaps due to using the same idempotent key).
429 - Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors	Something went wrong on Mono's end. (These are rare.)
200 - OK	Everything worked as expected 😊

Error Handling

While working on your Mono integration, we highly advise that you keep a log of all API requests you make and the responses you receive. Keep a log file as part of your application and record the API signature, any API URL parameters, and request body (you may strip the API keys) (JSON). Write down the API response code. Log the JSON body of the error message if one occurs. When your integration is stable, you can lower the logging level and log only the API name (signature), the response code, and any error messages that may have occurred.

In the Mono dashboard, you can also see the logs of each API call you make. This applies to both successful and failed responses (provided the access key and secret key are correct). Logs can be accessed by:

Log in to the Mono dashboard and navigate to Audit Logs > API Logs.
Use the dropdown at the top right navigation bar to select the mono application, or filter by Scope (identity, statements etc), Status (failed or successful) and Environment (live or test).
To view API call data that was made is automatically rendered based on the dropdown choice above.

The response body will be empty if a standard HTTP error code, such as 401 (Not Authorized) or 404 (Not Found), is sufficiently descriptive. The response will also contain an error entity that provides additional information about the incident, including an application error code and a human-readable error description. In other situations, we will utilize the standard response code for client errors (400).