API Errors

The Onvera API returns standard HTTP status codes and structured error responses.

Error Response Format

All error responses follow this format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "operation_id": "op_xxx"  // For async operations
  }
}

HTTP Status Codes

400 Bad Request

Invalid request parameters or body.

Common codes:

• INVALID_REQUEST - Invalid request parameters
• VALIDATION_ERROR - Request validation failed

Example:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid app_type. Must be 'airflow' or 'superset'"
  }
}

401 Unauthorized

Authentication failed.

Common codes:

• INVALID_API_KEY - API key is invalid
• MISSING_API_KEY - API key header is missing
• API_KEY_EXPIRED - API key has expired
• API_KEY_REVOKED - API key has been revoked

Example:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

403 Forbidden

Authorization failed.

Common codes:

• INSUFFICIENT_SCOPE - API key lacks required scope
• ACCESS_DENIED - Access denied to resource

Example:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Insufficient scope. Required: deployments:write"
  }
}

404 Not Found

Resource not found.

Common codes:

• DEPLOYMENT_NOT_FOUND - Deployment not found
• OPERATION_NOT_FOUND - Operation not found
• ENVIRONMENT_NOT_FOUND - Environment not found

Example:

{
  "error": {
    "code": "DEPLOYMENT_NOT_FOUND",
    "message": "Deployment not found"
  }
}

409 Conflict

Resource conflict.

Common codes:

• RESOURCE_CONFLICT - Resource already exists or is in conflicting state

Example:

{
  "error": {
    "code": "RESOURCE_CONFLICT",
    "message": "Deployment is already being destroyed"
  }
}

429 Too Many Requests

Rate limit exceeded.

Common codes:

• RATE_LIMIT_EXCEEDED - Too many requests

Example:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after 60 seconds"
  }
}

500 Internal Server Error

Server error.

Common codes:

• INTERNAL_ERROR - Internal server error
• SERVICE_UNAVAILABLE - Service temporarily unavailable

Example:

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal error occurred. Please try again later"
  }
}

Error Codes Reference

Authentication Errors

Authorization Errors

Resource Errors

Request Errors

Rate Limit Errors

Server Errors

Error Handling Best Practices

1. Check HTTP status code first
2. Parse error code for programmatic handling
3. Display error message to users
4. Retry with backoff for 5xx errors
5. Don't retry 4xx errors (except 429)
6. Handle rate limits with exponential backoff
7. Log errors for debugging

Retry Logic

Retryable Errors

• 5xx errors - Server errors (retry with backoff)
• 429 Too Many Requests - Rate limit (retry after delay)

Non-Retryable Errors

• 4xx errors (except 429) - Client errors (don't retry)
• 401 Unauthorized - Authentication failed (fix API key)
• 403 Forbidden - Authorization failed (fix scopes)
• 404 Not Found - Resource not found (check ID)

Related Concepts

• Rate Limits - Rate limiting details
• Reference: Error Codes - Complete error code reference