API Error Codes

Understanding API error codes is crucial for debugging and building robust applications. This guide outlines the common error codes returned by our API, their meanings, and suggested actions.

400 Bad Request Client Error

The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

Example Scenario

Sending an API request with missing required parameters or incorrectly formatted JSON payload.

{
    "error": {
        "code": "INVALID_REQUEST",
        "message": "Missing required 'user_id' parameter."
    }
}

Action: Review your request payload and ensure all required parameters are present and correctly formatted according to the API documentation.

401 Unauthorized Client Error

The request requires user authentication. The client might not have provided credentials or the provided credentials are invalid.

Example Scenario

Making a request to a protected endpoint without an API key or with an expired/invalid token.

{
    "error": {
        "code": "UNAUTHENTICATED",
        "message": "Authentication credentials not provided or invalid."
    }
}

Action: Ensure you have included a valid API key or authentication token in your request headers. If using OAuth, verify the token's validity and scope.

403 Forbidden Client Error

The server understood the request, but refuses to authorize it. This is different from 401 Unauthorized because it means the identity of the client is known to the server, but the client does not have permission to perform the requested action.

Example Scenario

A user with read-only permissions attempting to perform a write operation (e.g., update or delete).

{
    "error": {
        "code": "PERMISSION_DENIED",
        "message": "You do not have permission to perform this action."
    }
}

Action: Verify that the authenticated user or API key has the necessary permissions for the requested operation. Consult your account settings or administrator.

404 Not Found Client Error

The server can not find the requested resource. This may be because the resource does not exist or because the request URL is incorrect.

Example Scenario

Requesting an API endpoint that does not exist or referencing a non-existent resource ID.

{
    "error": {
        "code": "RESOURCE_NOT_FOUND",
        "message": "The requested resource could not be found."
    }
}

Action: Double-check the URL for typos and ensure that the resource you are trying to access actually exists and is accessible via the API.

429 Too Many Requests Client Error

The user has sent too many requests in a given amount of time ("rate limiting").

Example Scenario

Exceeding the allowed number of API calls within the specified time window.

{
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "You have exceeded your allowed request rate. Please try again later."
    }
}

Action: Implement backoff strategies in your application. Check the Retry-After header for guidance on when to resubmit the request. Refer to our Rate Limiting guide.

500 Internal Server Error Server Error

The server encountered an unexpected condition that prevented it from fulfilling the request. This is a generic error message when no more specific message is suitable.

Example Scenario

An unexpected bug or overload on the server caused the request to fail.

{
    "error": {
        "code": "INTERNAL_SERVER_ERROR",
        "message": "An unexpected error occurred. Please try again later or contact support if the problem persists."
    }
}

Action: This error is on our end. Please try the request again after a short while. If the issue persists, please contact our support team with details of your request.

503 Service Unavailable Server Error

The server is not ready to handle the request. This may be due to a temporary overload or maintenance.

Example Scenario

The API is temporarily down for maintenance or experiencing a high load.

{
    "error": {
        "code": "SERVICE_UNAVAILABLE",
        "message": "The service is temporarily unavailable. Please try again later."
    }
}

Action: The service should be back online shortly. Please try your request again later. Check our status page for updates.

Custom Error Codes

In addition to standard HTTP status codes, our API may return custom error codes within the response body for more specific error handling.

Example: Custom Business Logic Error

POST /api/v1/users
{
    "error": {
        "code": "INSUFFICIENT_BALANCE",
        "message": "Your account balance is insufficient to complete this transaction.",
        "details": {
            "required": "100.00",
            "available": "50.50"
        }
    }
}

Always refer to the specific API endpoint documentation for details on potential custom error codes.