Error Handling

When a request fails — blocked by security, rate limited, or provider error — CloudVera returns a structured error response. All errors follow the same format so you can handle them consistently.

HTTP Status	Error Code	Meaning
400	security_blocked	Request blocked by security pipeline (prompt injection, PII, toxic content, guardrail violation)
401	no_api_key	Missing or invalid CloudVera virtual key, or missing X-Provider-Key header
429	rate_limit_exceeded	Too many requests — check Retry-After header for seconds until reset
429	budget_exceeded	Monthly or daily spending cap reached for this virtual key
503	circuit_open	Provider temporarily unavailable — circuit breaker is open, auto-recovers
500	provider_error	Upstream provider returned an error (model overloaded, invalid request, etc.)
500	timeout	Request timed out waiting for the provider response

Code Examples

Error response format

{
  "error": {
    "code": "security_blocked",
    "message": "Prompt injection detected: instruction override attempt",
    "details": {
      "issues": [
        {
          "type": "injection_detected",
          "severity": "high",
          "description": "Detected instruction override pattern"
        }
      ]
    }
  }
}

Handling errors (Node.js)

try {
  const completion = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: userInput }],
  });
  return completion.choices[0].message.content;
} catch (error) {
  if (error.status === 400) {
    // Security blocked — prompt injection, PII, or policy violation
    console.error('Request blocked:', error.message);
    return 'Your message was blocked by our safety system.';
  }
  if (error.status === 429) {
    // Rate limited or budget exceeded
    const retryAfter = error.headers?.['retry-after'];
    console.error('Rate limited, retry after:', retryAfter, 'seconds');
    return 'Too many requests. Please try again later.';
  }
  if (error.status === 503) {
    // Provider down — circuit breaker open
    console.error('Provider unavailable, will auto-recover');
    return 'AI service temporarily unavailable. Please try again.';
  }
  throw error; // Unexpected error
}

Handling errors (Python)

from openai import OpenAI, APIError, RateLimitError

try:
    completion = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": user_input}],
    )
    return completion.choices[0].message.content
except RateLimitError as e:
    print(f"Rate limited: {e.message}")
    return "Too many requests. Please try again later."
except APIError as e:
    if e.status_code == 400:
        print(f"Security blocked: {e.message}")
        return "Your message was blocked by our safety system."
    raise