Errors

This document outlines the error handling mechanisms implemented in our API. It provides details on the error codes, response formats, and handling of various exception types.

We use 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, an action failed, etc). Codes in the 5xx range indicate an error with our servers (these are rare).

Some common error responses are listed below:

400 Bad Request - Your request may be malformed

401 Unauthorized - Your API key is wrong, or your user does not have access to this resource

403 Forbidden - The record requested is hidden

404 Not Found - The specified record could not be found

405 Method Not Allowed - You tried to access a record with an invalid method

​

Error Response Format

The API adheres to a consistent error response format to enhance user experience and simplify error interpretation. Here’s the general structure:

{
  "error_code": "<STRING>",  // Unique identifier for the error type
  "detail": [                // Array of detailed error messages (optional)
    {
      "message": "<STRING>",   // Descriptive message explaining the error
      "field": "<STRING>"     // (Optional) Field associated with the error (relevant for validation errors)
    },
    ...
  ]
}

AND

{
  "error": "<STRING>",  // Unique identifier for the error type
  "message": "<STRING>",   // Descriptive message explaining the error
}

​

Error Codes and Descriptions

The API returns specific error codes to convey the nature of the issue. Here’s a breakdown of the commonly encountered codes:

​

INVALID_INPUT (HTTP Status: 400):

Indicates errors related to invalid or malformed user input during API requests. The detail section will provide specific messages and potentially the fields where the errors occurred.

Example:

{
    "error_code": "INVALID_INPUT",
    "detail": [
        {
            "message": "Input should be a valid number, unable to parse string as a number",
            "field": "invoice.amount"
        },
        {
            "message": "Field required",
            "field": "invoice.invoice_number"
        }
    ]
}

​

VALIDATION_ERROR (HTTP Status: 400):

Occurs when validation constraints are violated during data processing. The detail section will contain a general error message.

Example:

{
    "error_code": "VALIDATION_ERROR",
    "message": "Payments are disabled for this company"
}

​

AUTHENTICATION_ERROR (HTTP Status: 401):

Occurs when user authentication fails due to invalid credentials, missing authentication headers, or insufficient permissions.

​

NOT_FOUND (HTTP Status: 404):

Returned when the requested resource does not exist on the server.

Example:

{
    "error_code": "NOT_FOUND",
    "message": "Invoice not found"
}

​

REQUEST_DATA_TOO_BIG (HTTP Status: 413):

The error response indicates that the request body was larger than the limit (10 MB).

​

Additional Notes

For security reasons, avoid exposing sensitive details in the error messages, especially when dealing with authentication errors.