Error Handling

Understanding error codes, responses, and troubleshooting API errors

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

Show child attributes

message · string

Human-readable description of the error

field · string

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

status · integer

HTTP status code

message · string

Top-level error message summarizing the issue

Common error scenarios

Authentication errors

401 - Invalid token

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

400 - Missing required field

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

404 - Project not found

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

Python retry example

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:

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

Related resources

• Authentication
• API Overview
• Full API reference