Error Handling

Error Response Format

All errors follow the OpenAI error format. The response body is JSON with an error object:

{
  "error": {
    "message": "Human-readable description of what went wrong",
    "type": "error_type",
    "code": "specific_error_code"
  }
}

400Guardrail Block

Returned when a request violates a compliance policy — content safety, prompt injection, or PII policy configured to block.

{
  "error": {
    "message": "Request blocked by content safety policy: violence score 0.92 exceeds threshold 0.5",
    "type": "guardrail_violation",
    "code": "content_safety_block"
  }
}

try:
    response = client.chat.completions.create(...)
except openai.BadRequestError as e:
    body = e.body  # parsed JSON error
    if body.get("error", {}).get("code") == "content_safety_block":
        print("Content was blocked by safety policy")
    elif body.get("error", {}).get("code") == "prompt_injection_detected":
        print("Prompt injection attempt was blocked")

401Unauthorized

Missing or invalid API key. Keys must start with dai_sk_.

{
  "error": {
    "message": "Invalid API key. Get one at agilecloud.ai/dashboard",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

403Tier Restricted

The requested model requires a higher subscription tier than your current plan.

{
  "error": {
    "message": "Model 'gpt-5' requires Business tier or above. Current tier: Pro",
    "type": "permission_error",
    "code": "tier_restricted"
  }
}

429Rate Limit Exceeded

You have exceeded your per-minute request or token limit. The response includes Retry-After header.

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit-Requests: 20
X-RateLimit-Remaining-Requests: 0
X-RateLimit-Reset-Requests: 12s

{
  "error": {
    "message": "Rate limit reached: 20 RPM. Retry after 12 seconds.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

import time
import openai

try:
    response = client.chat.completions.create(...)
except openai.RateLimitError as e:
    retry_after = int(e.response.headers.get("Retry-After", 60))
    print(f"Rate limited. Retrying in {retry_after}s...")
    time.sleep(retry_after)
    response = client.chat.completions.create(...)  # retry

502Backend Error

The upstream model provider (Azure AI Foundry, OpenAI, Anthropic, etc.) returned an error or timed out. ACAI could not get a response from the inference backend.

{
  "error": {
    "message": "Backend error: upstream provider returned 503",
    "type": "backend_error",
    "code": "upstream_unavailable"
  }
}

503Service Unavailable

ACAI is temporarily unable to handle requests — typically during deployments or maintenance windows.

{
  "error": {
    "message": "Service temporarily unavailable. Please retry.",
    "type": "server_error",
    "code": "service_unavailable"
  }
}

Correlation IDs

Every response (including errors) includes an X-Request-ID header. Include this ID when contacting support — it lets us trace the full request lifecycle through our audit logs.

X-Request-ID: req_a1b2c3d4-e5f6-7890-abcd-ef1234567890

Best Practices

• Always check the error.code field for programmatic handling — not the message string.
• Implement exponential backoff for 429 and 502/503 errors.
• Log the X-Request-ID from every failed request for debugging.
• Use the OpenAI SDK's built-in retry logic — it handles rate limits automatically.
• For guardrail blocks (400), review your compliance policy settings in the dashboard.