Error Handling

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)

success

The request succeeded. The response body contains the requested data.

success

A resource was successfully created. The response includes the new resource details.

success

The request has been accepted for processing but is not yet complete. Common for long-running operations.

success

The request succeeded but there’s no content to return. Common for DELETE operations.

Client error codes (4xx)

error

The request is malformed or contains invalid parameters. Check your request body and query parameters.

error

Authentication failed or no authentication token was provided. Verify your token is valid and properly formatted.

error

The authenticated user doesn’t have permission to access this resource. Check your organization and project permissions.

error

The requested resource doesn’t exist. Verify the resource name or ID.

error

The request conflicts with the current state of the resource. For example, trying to create a resource that already exists.

error

You’ve exceeded the API rate limit. Implement exponential backoff and retry logic.

Server error codes (5xx)

error

An unexpected error occurred on the server. Retry the request, and contact support if the issue persists.

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"
}

array

Array of error objects with detailed information

Show child attributes

string

Human-readable description of the error

string

The specific field that caused the error (for validation errors)

integer

HTTP status code

string

Top-level error message summarizing the issue

Common error scenarios

Authentication errors

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

{
  "errors": [
    {
      "message": "Token has expired",
      "status": 401
    }
  ],
  "message": "Token has expired"
}

{
  "errors": [
    {
      "message": "Forbidden: You do not have permission to access this resource",
      "status": 403
    }
  ],
  "message": "Forbidden"
}

Validation errors

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

{
  "errors": [
    {
      "message": "Invalid cloud region: invalid-region-1",
      "field": "cloud",
      "status": 400
    }
  ],
  "message": "Bad request"
}

{
  "errors": [
    {
      "message": "Service with name 'my-service' already exists",
      "status": 409
    }
  ],
  "message": "Conflict"
}

Resource errors

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

{
  "errors": [
    {
      "message": "Service 'my-service' not found in project 'my-project'",
      "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 retry logic

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 before sending

Validate request parameters client-side before making API calls to avoid unnecessary round trips and rate limit consumption.

Log error details

Log complete error responses including status codes, messages, and affected fields for easier troubleshooting.

Handle errors gracefully

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

Check service status

When encountering persistent 5xx errors, check the Aiven status page for ongoing incidents.

Use idempotency keys

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"}
)

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429 || response.status >= 500) {
        const waitTime = Math.pow(2, i) * 1000; // Exponential backoff
        await new Promise(resolve => setTimeout(resolve, waitTime));
        continue;
      }
      
      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

Getting help

If you encounter persistent errors or unexpected behavior:

Check the full API documentation for endpoint-specific details
Review the Aiven status page for service incidents
Search the Aiven community forum for similar issues
Contact Aiven support with error details and request IDs

Getting Started

Endpoints

Error Handling

HTTP status codes

Success codes (2xx)

Client error codes (4xx)

Server error codes (5xx)

Error response format

Common error scenarios

Authentication errors

Validation errors

Resource errors

Rate limiting

Error handling best practices

Rate limiting details

Getting help

​HTTP status codes

​Success codes (2xx)

​Client error codes (4xx)

​Server error codes (5xx)

​Error response format

​Common error scenarios

​Authentication errors

​Validation errors

​Resource errors

​Rate limiting

​Error handling best practices

​Rate limiting details

​Getting help

​Related resources

HTTP status codes

Success codes (2xx)

Client error codes (4xx)

Server error codes (5xx)

Error response format

Common error scenarios

Authentication errors

Validation errors

Resource errors

Rate limiting

Error handling best practices

Rate limiting details

Getting help

Related resources