Error Handling

This API provides detailed error information in its responses to help clients diagnose and resolve issues. The following sections explain how errors are handled, the structure of error responses, and the relevant HTTP status codes.

Error Response Structure

When an error occurs, the API responds with a JSON object containing specific details about the error. This object includes two key fields:

• errorMessage: A descriptive message explaining what went wrong.
• errorCode: A unique identifier for the specific error type, useful for programmatic error handling.

Example Error Response (JSON Format)

{
  "error": {
    "message": "The provided country ISO code is not valid. Please provide a valid ISO 3166-1 alpha-2 country code.",
    "code": "invalid_country_iso_code"
  }
}

In this example, the error indicates that an invalid country ISO code was provided.

Alternate Error Response (String Format)

Some endpoints may currently return errors as a plain string containing the error message, though we are actively working to standardize all responses into the structured JSON format described above.

Example:

"The provided country ISO code is not valid."

We recommend handling both formats, although the goal is to fully transition to JSON-based error responses.

Localized Error Messages

Whenever appropriate, error messages will be localized based on the request's locale settings, providing users with error descriptions in their preferred language. This enhances user experience and ensures clear communication of issues.

HTTP Response Codes

The API follows standard HTTP status codes to indicate the success or failure of a request. Below are common HTTP codes returned in case of errors:

• 400 Bad Request: The request could not be understood or was missing required parameters (e.g., invalid input data).
• 401 Unauthorized: Authentication failed or the user does not have permissions for the desired action.
• 403 Forbidden: The request was understood, but it has been refused or access is not allowed.
• 404 Not Found: The requested resource could not be found.
• 409 Conflict: The request conflicts with the current state of the server. (e.g. trying to create a resource that already exists).
• 414 URI Too Long: The URI requested by the client is longer than the server is willing to interpret.
• 500 Internal Server Error: The server encountered an error and could not complete the request.

These status codes are included in the HTTP response, while the details of the error are provided in the response body.