Skip to main content
The Aiven API uses conventional HTTP status codes to indicate the success or failure of requests. Error responses include detailed information to help diagnose and resolve issues.

​
HTTP status codes

The API returns standard HTTP status codes:

​
Success codes (2xx)

​
200 OK
success
The request succeeded. The response body contains the requested data.
​
201 Created
success
A resource was successfully created. The response includes the new resource details.
​
202 Accepted
success
The request has been accepted for processing but is not yet complete. Common for long-running operations.
​
204 No Content
success
The request succeeded but there’s no content to return. Common for DELETE operations.

​
Client error codes (4xx)

​
400 Bad Request
error
The request is malformed or contains invalid parameters. Check your request body and query parameters.
​
401 Unauthorized
error
Authentication failed or no authentication token was provided. Verify your token is valid and properly formatted.
​
403 Forbidden
error
The authenticated user doesn’t have permission to access this resource. Check your organization and project permissions.
​
404 Not Found
error
The requested resource doesn’t exist. Verify the resource name or ID.
​
409 Conflict
error
The request conflicts with the current state of the resource. For example, trying to create a resource that already exists.
​
429 Too Many Requests
error
You’ve exceeded the API rate limit. Implement exponential backoff and retry logic.

​
Server error codes (5xx)

​
500 Internal Server Error
error
An unexpected error occurred on the server. Retry the request, and contact support if the issue persists.
​
503 Service Unavailable
error
The API is temporarily unavailable. Retry the request after a brief delay.

​
Error response format

Error responses follow a consistent JSON structure: 
{
  "errors": [
    {
      "message": "Human-readable error description",
      "field": "field_name",
      "status": 400
    }
  ],
  "message": "Primary error message"
}
​
errors
array
Array of error objects with detailed information
​
message
string
Top-level error message summarizing the issue

​
Common error scenarios

​
Authentication errors

{
  "errors": [
    {
      "message": "Invalid token",
      "status": 401
    }
  ],
  "message": "Invalid token"
}

​
Validation errors

{
  "errors": [
    {
      "message": "Missing required field: service_type",
      "field": "service_type",
      "status": 400
    }
  ],
  "message": "Bad request"
}

​
Resource errors

{
  "errors": [
    {
      "message": "Project 'non-existent-project' not found",
      "status": 404
    }
  ],
  "message": "Not found"
}

​
Rate limiting

429 - Too many requests
{
  "errors": [
    {
      "message": "Rate limit exceeded. Please retry after 60 seconds",
      "status": 429
    }
  ],
  "message": "Too many requests"
}

​
Error handling best practices

Implement exponential backoff for retrying failed requests, especially for 429 (rate limit) and 5xx (server error) responses.
import time
import requests

def make_request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        
        if response.status_code == 200:
            return response.json()
        
        if response.status_code == 429 or response.status_code >= 500:
            wait_time = 2 ** attempt  # Exponential backoff
            time.sleep(wait_time)
            continue
        
        # For other errors, don't retry
        response.raise_for_status()
    
    raise Exception(f"Max retries ({max_retries}) exceeded")
Validate request parameters client-side before making API calls to avoid unnecessary round trips and rate limit consumption.
Log complete error responses including status codes, messages, and affected fields for easier troubleshooting.
Provide meaningful error messages to end users while logging technical details for debugging.
try:
    response = requests.post(url, json=data, headers=headers)
    response.raise_for_status()
    return response.json()
except requests.exceptions.HTTPError as e:
    error_data = e.response.json()
    print(f"API Error: {error_data.get('message')}")
    for error in error_data.get('errors', []):
        print(f"  - {error.get('message')}")
    raise
When encountering persistent 5xx errors, check the Aiven status page for ongoing incidents.
For critical operations, implement idempotency to safely retry requests without duplicating resources.

​
Rate limiting details

The Aiven API implements rate limiting to ensure fair usage:
  • Rate limits are applied per authentication token
  • Different endpoints may have different rate limits
  • When rate limited, wait for the time specified in the error message
  • Implement exponential backoff starting with a 1-second delay
import time
import requests
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry

def create_session_with_retries():
    session = requests.Session()
    retry_strategy = Retry(
        total=3,
        status_forcelist=[429, 500, 502, 503, 504],
        backoff_factor=1,  # Wait 1, 2, 4 seconds
    )
    adapter = HTTPAdapter(max_retries=retry_strategy)
    session.mount("https://", adapter)
    return session

session = create_session_with_retries()
response = session.get(
    "https://api.aiven.io/v1/project",
    headers={"Authorization": "aivenv1 YOUR_TOKEN"}
)

​
Getting help

If you encounter persistent errors or unexpected behavior:
  1. Check the full API documentation for endpoint-specific details
  2. Review the Aiven status page for service incidents
  3. Search the Aiven community forum for similar issues
  4. Contact Aiven support with error details and request IDs

Build docs developers (and LLMs) love

Get started for freeTalk to us