API Error Documentation

This section details the common error responses you might encounter when interacting with our API. Understanding these errors will help you build more robust and resilient applications.

Standard Error Structure

All error responses adhere to a consistent JSON structure:

{
    "error": {
        "code": "ERROR_CODE_IDENTIFIER",
        "message": "A human-readable description of the error.",
        "details": "Optional additional technical details or context."
    }
}

Common HTTP Status Codes and Errors

400 Bad Request
Invalid Request

The server could not understand your request due to invalid syntax, missing parameters, or malformed data.

Example Error Codes:

  • INVALID_PARAMETER: A required parameter is missing or has an invalid value.
  • MALFORMED_JSON: The request body is not valid JSON.
  • DATA_VALIDATION_FAILED: The provided data failed validation rules.
{
    "error": {
        "code": "INVALID_PARAMETER",
        "message": "The 'user_id' parameter is required and must be a valid UUID.",
        "details": "Received 'user_id': 'abc-123' (expected format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)"
    }
}
401 Unauthorized
Authentication Required

Your request requires authentication, but you did not provide valid credentials or your credentials have expired.

Example Error Codes:

  • UNAUTHENTICATED: No authentication credentials provided.
  • INVALID_API_KEY: The provided API key is invalid or inactive.
  • TOKEN_EXPIRED: The authentication token has expired.
{
    "error": {
        "code": "UNAUTHENTICATED",
        "message": "Authentication credentials were not provided."
    }
}
403 Forbidden
Permission Denied

You are authenticated, but you do not have the necessary permissions to perform the requested action.

Example Error Codes:

  • INSUFFICIENT_PERMISSIONS: The authenticated user lacks the required roles or permissions.
{
    "error": {
        "code": "INSUFFICIENT_PERMISSIONS",
        "message": "You do not have permission to access this resource.",
        "details": "Required roles: 'admin', 'editor'. Your roles: 'viewer'."
    }
}
404 Not Found
Resource Not Found

The requested resource could not be found on the server. This often means the URL path is incorrect or the specified identifier does not exist.

Example Error Codes:

  • RESOURCE_NOT_FOUND: The specific resource (e.g., user, document) does not exist.
{
    "error": {
        "code": "RESOURCE_NOT_FOUND",
        "message": "The user with the specified ID was not found.",
        "details": "User ID: 'f47ac10b-58cc-4372-a567-0e02b2c3d479'"
    }
}
429 Too Many Requests
Rate Limit Exceeded

You have exceeded the allowed number of requests within a given time period. Please refer to the Rate Limiting documentation.

Example Error Codes:

  • RATE_LIMIT_EXCEEDED: General rate limit violation.
  • BURST_RATE_LIMIT_EXCEEDED: Exceeded the rapid request limit.
{
    "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "You have exceeded the rate limit. Please try again later.",
        "details": "Reset time: 2023-10-27T10:30:00Z"
    }
}
500 Internal Server Error
Server Error

An unexpected error occurred on our server. This is usually a temporary issue. If the problem persists, please contact support.

Example Error Codes:

  • INTERNAL_SERVER_ERROR: A generic server-side error.
  • DATABASE_ERROR: An issue connecting to or querying the database.
{
    "error": {
        "code": "INTERNAL_SERVER_ERROR",
        "message": "An unexpected error occurred. Please try again later or contact support."
    }
}
It's crucial to implement proper error handling in your application to gracefully manage these responses and provide a good user experience.

Custom Error Codes

In addition to standard HTTP errors, we may use custom error codes for specific business logic failures. These will typically be returned with a 400 or 422 status code.

Always check the error.code field in the JSON response for specific details.