Error Handling

Overview

The Covolt API uses standard HTTP status codes and structured response bodies to communicate success or error conditions. This consistent approach makes error handling predictable across all API endpoints.

HTTP Status Codes

Our API follows RESTful conventions for status codes:

Status Code Range	Category	Description
200 - 299	Success	The request was successfully received, understood, and processed
400 - 499	Client Error	The request contains errors or cannot be fulfilled due to client-side issues
500 - 599	Server Error	The server encountered an error while processing the request

Common Status Codes

Status Code	Description	Typical Causes
200 OK	Request succeeded	Standard success response for GET requests
201 Created	Resource created	Successful POST request that created a new resource
204 No Content	Success, no content to return	Successful DELETE or certain PUT requests
400 Bad Request	Invalid request format	Malformed JSON, invalid parameters
401 Unauthorized	Authentication required	Missing or invalid API token
403 Forbidden	Permission denied	Valid authentication but insufficient permissions
404 Not Found	Resource not found	Invalid endpoint or resource ID
422 Unprocessable Entity	Validation error	Request data failed validation rules
429 Too Many Requests	Rate limit exceeded	Too many requests in a given time frame
500 Internal Server Error	Server error	Unexpected error on the server
503 Service Unavailable	Service temporarily unavailable	Server is overloaded or under maintenance

Error Response Format

Non-Validation Errors

For most errors, responses include a detail field:

{
  "detail": "Authentication credentials were not provided."
}

Validation Errors

For validation errors (400 Bad Request), responses include field-specific messages:

{
  "name": ["This field is required."],
  "email": ["Enter a valid email address."]
}

Common Error Codes

The API uses standard HTTP status codes to communicate error types:

Status Code	Description	Example Situation
400 Bad Request	The request was malformed or contains invalid parameters	Field validation errors, invalid JSON
401 Unauthorized	No valid authentication credentials provided	Missing or invalid API token
403 Forbidden	User lacks permission for the requested operation	Attempting to access restricted resource
404 Not Found	The requested resource does not exist	Invalid endpoint or resource ID
405 Method Not Allowed	The HTTP method is not supported for this endpoint	Using POST on a GET-only endpoint
429 Too Many Requests	API rate limit has been exceeded	Too many requests in given timeframe
500 Internal Server Error	An unexpected error occurred on the server	Server-side exception

Best Practices

• Implement retry logic with exponential backoff for 429 and 5xx errors
• Cache responses where appropriate to reduce request volume
• Use batch endpoints for bulk operations when available

Best Practices for Error Handling

1. Always check status codes: Never assume a request will succeed.

2. Parse error details: Extract detailed error information from the response body.

3. Implement retry logic: For 429 or 5xx errors, implement backoff and retry.

4. Log comprehensive details: Log the full error response for troubleshooting.

5. Present user-friendly messages: Translate API error messages into actionable user feedback.

Validation Errors

For validation errors, each invalid field is included as a key with an array of error messages:

{
  "name": ["This field is required."],
  "email": ["Enter a valid email address."],
  "age": ["Ensure this value is greater than or equal to 18."]
}