Error Handling

When working with APIs, things don't always go as planned. This guide will help you understand how to interpret and handle errors you might encounter while using our API.

You can determine if your request was successful by checking the status code of the API response. If a response is unsuccessful, you can use the error code and message to identify what went wrong and how to resolve it.

Error Response Structure

All error responses from our API follow a consistent structure to help you quickly identify and resolve issues.

Every error response includes:

  • A status code
  • An error code
  • A human-readable message

This structure allows for easy debugging and consistent error handling in your applications.

Error response structure

{
  "error": "ERROR_CODE",
  "message": "Description of the error."
}

Status Codes

Here's a list of the different categories of status codes you might encounter:

  • Name
    2xx
    Description

    Indicates a successful response.

  • Name
    4xx
    Description

    Indicates a client error — this usually means there's an issue with your request.

  • Name
    5xx
    Description

    Indicates a server error — these are rare and usually temporary.

Common Errors

Here are some common errors you might encounter while using our API:

  • Name
    UNAUTHORIZED
    Description

    Invalid API key or unauthorized access. Check your credentials and ensure your API key is included in the Authorization header.

  • Name
    BAD_REQUEST
    Description

    Missing or invalid parameters in your request. Review the request and ensure all required parameters are included and properly formatted.

  • Name
    RATE_LIMIT_EXCEEDED
    Description

    You've exceeded the rate limit for requests. Implement exponential back-off in your retry strategy or consider upgrading your usage plan.

  • Name
    INTERNAL_SERVER_ERROR
    Description

    An unexpected error occurred on our server. These are rare and usually temporary. Try again later and report persistent issues to our support team.

  • Name
    SERVICE_UNAVAILABLE
    Description

    The service is temporarily unavailable due to maintenance or high load. Wait and retry your request. Contact support if the issue persists.

  • Name
    NOT_FOUND
    Description

    The requested resource was not found. Check the URL and parameters of your request.

Example error response

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "You have exceeded the rate limit for requests. Please wait before making additional requests."
}

When encountering errors, always check the error and message in the response. These will provide specific guidance on how to resolve the issue or what action to take next.

Was this page helpful?