Error Codes

The Panda World API uses standard HTTP status codes and returns JSON error bodies consistent with the OpenAI error format.

Error Response Format

{
  "error": {
    "message": "Insufficient balance",
    "type": "insufficient_balance",
    "code": "insufficient_funds",
    "param": null
  }
}

HTTP Status Codes

Status	Code	Description
200	-	Success
400	`invalid_request_error`	Malformed request — check parameters, headers, or request body
401	`authentication_error`	Invalid, missing, or revoked API key
402	`insufficient_balance`	Your account balance is too low to process this request
404	`not_found`	The requested resource or model was not found
429	`rate_limit_error`	Too many requests — slow down
500	`api_error`	Internal server error — try again later
502	`upstream_error`	Upstream model provider returned an error
503	`service_unavailable`	Service temporarily unavailable — maintenance or overload

Common Error Scenarios

Authentication Error (401)

{
  "error": {
    "message": "Incorrect API key provided: sk-***abc. Check your key is correct.",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}

Fix: Check your API key is correct and hasn't been revoked.

Insufficient Balance (402)

{
  "error": {
    "message": "Your account balance ($0.50) is insufficient for this request. Estimated cost: $0.75",
    "type": "insufficient_balance",
    "code": "insufficient_funds",
    "param": null
  }
}

Fix: Top up your account via the Dashboard.

Rate Limited (429)

{
  "error": {
    "message": "Rate limit exceeded: 100 requests per minute",
    "type": "rate_limit_error",
    "code": "rate_limited",
    "param": null
  }
}

Fix: Implement exponential backoff in your client. Check theRetry-After header for guidance.

Model Not Found (404)

{
  "error": {
    "message": "The model 'gpt-4o' does not exist",
    "type": "not_found",
    "code": "model_not_found",
    "param": null
  }
}

Fix: Check the correct model ID in our Models & Pricing page.

Rate Limit Headers

All API responses include rate limit headers:

Header	Description
`X-RateLimit-Limit`	Max requests per minute allowed
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait before retrying (only on 429)

Best Practices

Always handle 401 errors by checking your API key
Implement exponential backoff with jitter for 429 and 5xx errors
Monitor your balance to avoid 402 errors
Retry 502/503 errors after a short delay — they are usually transient