API Error Codes Reference

This document describes all possible error responses returned by AGIPower platform APIs, including root causes and troubleshooting steps.

Error Response Format

All errors follow a unified JSON structure:

{
  "error": {
    "code": "429",
    "type": "rate_limit",
    "message": "Rate limit exceeded"
  }
}

Field	Type	Description
`code`	string	HTTP status code (as a string)
`type`	string	Error type
`message`	string	Error description

Error Quick Reference

HTTP Status	Error Type	Description
400	`invalid_params`	Invalid request parameters
402	`insufficient_credit`	Account overdue
402	`reject_no_credit`	Insufficient balance
402	`quote_exceeded`	Subscription quota exhausted
403	`access_denied`	Invalid or missing API Key
403	`safety_check_failed`	Upstream safety policy triggered
404	`model_not_available`	Model not included in current subscription plan
404	`invalid_model`	Model does not exist
404	`model_not_supported`	Model does not support this API
413	`invalid_params`	Prompt too long
422	`provider_unprocessable_entity_error`	Upstream cannot process the request
429	`rate_limit`	Rate limit exceeded
500	`internal_server_error`	Platform internal error
500	`provider_api_error`	Upstream provider API returned an error
500	`provider_error`	Upstream provider service error
502	`no_provider_available`	No upstream provider available
520	`provider_internal_server_error`	Unable to communicate with provider
524	`provider_internal_server_error`	Provider timed out

Detailed Error Descriptions

Authentication & Authorization Errors

HTTP 403 — `access_denied`

{
  "error": {
    "code": "403",
    "type": "access_denied",
    "message": "You have no permission to access this resource"
  }
}

Cause: The API Key provided in the request is invalid, expired, or missing. Troubleshooting:

Verify that the API Key is correctly passed via the Authorization: Bearer <key>, x-api-key, or x-goog-api-key header.
Log in to the AGIPower Console to confirm that the API Key has not been revoked or expired.
Ensure there are no extra spaces or line breaks when copying the API Key.

HTTP 403 — `safety_check_failed`

Indicates that the input content was blocked by an upstream safety policy. Troubleshooting:

Adjust the prompt, images, files, or tool input content.
Reduce descriptions that may trigger safety rules.
Switch to a different model if necessary.

Parameter Validation Errors

HTTP 400 — `invalid_params`

Returned when request parameters fail validation. Specific scenarios are listed below:

Error Message	Cause	Solution
`Parameter model is required`	Missing or empty `model` field	Add a valid `model` value to the request body
`Model \{model\} is not valid`	Specified model identifier does not exist	Refer to the model list for valid model names
`Parameter messages is required`	Missing `messages` field	Include a `messages` array in the request body
`Parameter messages can not be empty`	`messages` is an empty array	Provide at least one message
`Parameter messages can not contain null elements`	`messages` contains `null` elements	Remove null items from the messages array
`Parameter messages can not contain elements without content`	Message object is missing the `content` field	Ensure every message includes a `content` value
`Parameter stream_options is not supported while stream is false`	`stream_options` is set but `stream` is `false` or unset	Set `stream: true` or remove `stream_options`
`Parameter n grater than 1 is not supported`	`n` value is greater than 1	Set `n` to 1 or omit the parameter
`Parameter temperature is not valid`	`temperature` is negative	Use a `temperature` value ≥ 0
`Parameter stream_options.include_usage conflict with usage.include`	`stream_options.include_usage` conflicts with `usage.include`	Use only one of the two parameters
`Parameter include_reasoning conflict with reasoning.exclude`	`include_reasoning` conflicts with `reasoning.exclude`	Use only one of the two parameters
`Parameter type of provider.routing is not valid`	Invalid provider routing type	Refer to the Provider Routing documentation
`Parameter providers of provider.routing is not valid`	Provider routing list is empty	Specify at least one provider

HTTP 413 — `invalid_params` (Prompt Too Long)

{
  "error": {
    "code": "413",
    "type": "invalid_params",
    "message": "Prompt is too long"
  }
}

Cause: The request body (including all messages) exceeds the model’s maximum context length. Troubleshooting:

Reduce the number or length of messages in the messages array.
Consider using a model that supports a larger context window.
Summarize earlier conversation turns instead of including the full history.

HTTP 422 — `provider_unprocessable_entity_error`

Cause: The request passed platform-side validation, but the upstream model provider was unable to process it. This typically occurs when the upstream provider has stricter requirements for field structure, tools, formatted output, or multimodal inputs. Troubleshooting:

Review the specific description in the message field of the response.
Check that all parameters are compatible with the selected model.
Remove optional/advanced parameters and retry with a minimal request.

Billing & Subscription Errors

HTTP 402 — `insufficient_credit` (Account Overdue)

{
  "error": {
    "code": "402",
    "type": "insufficient_credit",
    "message": "Account overdue. To prevent abuse, a non-negative balance is required for all models (including free tiers)."
  }
}

Cause: The account balance is negative (overdue). Troubleshooting:

Go to the AGIPower Billing page to top up your balance.

HTTP 402 — `reject_no_credit` (Insufficient Balance)

{
  "error": {
    "code": "402",
    "type": "reject_no_credit",
    "message": "Credit required. To prevent abuse, a positive balance is required for this model."
  }
}

Cause: The account balance is zero or extremely low, and the requested model requires a positive balance. Troubleshooting:

Top up your account balance.
Switch to a model or plan that allows low-balance access.

HTTP 402 — `quote_exceeded` (Subscription Quota Exhausted)

{
  "error": {
    "code": "402",
    "type": "quote_exceeded",
    "message": "You have reached your subscription quota limit. Please wait for automatic quota refresh in the rolling time window, upgrade to a higher plan, or use a Pay-As-You-Go API Key for unlimited access. Learn more: https://agipower.ai/docs/guide/subscription.html"
  }
}

Cause: The quota included in your current subscription plan has been exhausted. Solutions:

Wait for refresh — Quotas automatically replenish within the rolling time window.
Upgrade your plan — Switch to a higher-tier subscription for a larger quota.
Pay-As-You-Go — Create a Pay-As-You-Go API Key for unlimited usage (billed per token).

Model Availability Errors

HTTP 404 — `model_not_available` (Model Not in Subscription Plan)

{
  "error": {
    "code": "404",
    "type": "model_not_available",
    "message": "The requested model is not included in your subscription plan. Please create a Pay-As-You-Go API Key to access this model, or check available models for your plan at https://agipower.ai/docs/guide/subscription.html"
  }
}

Cause: The requested model exists but is not included in your current subscription plan. Troubleshooting:

Check the Subscription Guide to confirm which models are supported by your current plan.
Upgrade your subscription plan to include the target model.
Use a Pay-As-You-Go API Key to access models outside your plan.

HTTP 404 — `invalid_model` (Model Does Not Exist)

Cause: The specified model identifier does not match any known model. Troubleshooting:

Check for typos in the model name.
Refer to the model list for valid model identifiers.

HTTP 404 — `model_not_supported` (Model Does Not Support This API)

Cause: The model exists but does not support the API being called. Troubleshooting:

Check the model’s detail page to confirm which APIs it supports.
Switch to a model that supports the current API.

Rate Limiting Errors

HTTP 429 — `rate_limit`

{
  "error": {
    "code": "429",
    "type": "rate_limit",
    "message": "Rate limit exceeded"
  }
}

Cause: The request rate has exceeded the allowed limit. This may originate from platform-level rate limiting or upstream provider rate limiting. Troubleshooting:

Reduce request frequency — Add delays between requests or use an exponential backoff strategy.
Spread peak traffic — Distribute calls more evenly over time.

Server & Upstream Errors

HTTP 500 — `internal_server_error` (Platform Internal Error)

Cause: An unexpected server error occurred, possibly due to:

A transient platform failure.
An upstream error being consolidated into an internal error by the platform.

Troubleshooting:

Retry with backoff — Most 500 errors are transient and can be resolved with exponential backoff retries.
If the issue persists, contact support with the X-AGIPower-RequestId from the response headers.

HTTP 500 — `provider_error` / `provider_api_error`

Cause: The request reached the upstream provider, and the issue most likely originated on the provider’s side. Troubleshooting:

Retry with backoff
If the issue persists, contact support with the X-AGIPower-RequestId from the response headers.

HTTP 502 — `no_provider_available` — No Upstream Provider Available

Cause: No upstream provider is currently available to handle the request, possibly due to:

The specified provider does not exist.
All configured upstream providers for this model are experiencing failures.
All providers failed after multiple retries.

Troubleshooting:

Relax or remove provider-specific routing rules.
Wait briefly and retry.

Streaming Request Edge Cases

When using stream: true, errors may manifest differently:

Errors During Streaming

If an error occurs after streaming has started, it will not fall back to a standard JSON error body. Instead, the stream will terminate or emit a failure event within the stream. Clients should handle the following in streaming scenarios:

HTTP status code evaluation
Event stream completeness checks
Business-level end markers
In-stream error event parsing

SSE Keep-Alive Comments

During long-running requests, you may receive SSE comments like:

: AGIPower PROCESSING

This is not an error — it is a keep-alive signal sent every 10 seconds to prevent connection timeouts. Per the SSE specification, your client parser should ignore lines starting with :.

Stream Disconnection

If the client disconnects voluntarily (e.g., cancels the request), the server will clean up the in-progress stream and release resources. Client-initiated disconnections do not produce error responses.

Error Handling Best Practices

Always handle errors programmatically based on the type field — Use type for code logic; message is for display only.
Implement retry logic for retryable errors:

Retryable:      429, 500, 502, 503, 504
Non-retryable:  400, 402, 403, 404, 413, 422

Save the X-AGIPower-RequestId from response headers — Including this ID when contacting support helps expedite issue resolution.
Handle streaming responses gracefully — When using stream: true, always handle incomplete responses and connection interruptions.
Use exponential backoff for retries — Gradually increase the interval between retries (e.g., 1s → 2s → 4s → 8s), and add random jitter to avoid the “thundering herd” effect.

FAQ

Q: I have a positive balance, so why am I getting a 402 error? A: Check your API Key type. Subscription API Keys have independent quota limits that are separate from your account balance. When subscription quotas are exhausted, a 402 (quote_exceeded) error is returned even if your balance is sufficient. Check:

Your current subscription plan’s quota usage
Whether you are using the correct API Key type

Q: The same request works for some models but returns 404 for others. A: Different subscription plans include different model lists. Models not included in your current plan will return model_not_available. Solutions:

Review the model list for your subscription plan
Upgrade to a plan that includes the target model
Use a Pay-As-You-Go API Key for on-demand access

Q: I occasionally see 500 errors. Should I be concerned? A: Occasional 500 errors are normal in distributed systems. We recommend:

Implementing automatic retry mechanisms (with exponential backoff)
Contacting support if the error rate remains consistently high

Q: What rate limits apply to my API Key? A: Rate limits depend on your subscription plan tier. Log in to the AGIPower Console to view your current plan details. Q: How can I tell which upstream provider handled my request? A: For security and abstraction purposes, provider information in responses is anonymized. If you need to trace the request path, provide the X-AGIPower-RequestId from the response headers to the support team. Q: What does AGIPower PROCESSING mean during a streaming request? A: This is an SSE keep-alive comment (prefixed with :), sent every 10 seconds to indicate the request is still being processed. It is not an error — your SSE client should automatically ignore comment lines per the specification.

​API Error Codes Reference

​Error Response Format

​Error Quick Reference

​Detailed Error Descriptions

​Authentication & Authorization Errors

​HTTP 403 — access_denied

​HTTP 403 — safety_check_failed

​Parameter Validation Errors

​HTTP 400 — invalid_params

​HTTP 413 — invalid_params (Prompt Too Long)

​HTTP 422 — provider_unprocessable_entity_error

​Billing & Subscription Errors

​HTTP 402 — insufficient_credit (Account Overdue)

​HTTP 402 — reject_no_credit (Insufficient Balance)

​HTTP 402 — quote_exceeded (Subscription Quota Exhausted)

​Model Availability Errors

​HTTP 404 — model_not_available (Model Not in Subscription Plan)

​HTTP 404 — invalid_model (Model Does Not Exist)

​HTTP 404 — model_not_supported (Model Does Not Support This API)

​Rate Limiting Errors

​HTTP 429 — rate_limit

​Server & Upstream Errors

​HTTP 500 — internal_server_error (Platform Internal Error)

​HTTP 500 — provider_error / provider_api_error

​HTTP 502 — no_provider_available — No Upstream Provider Available

​Streaming Request Edge Cases

​Errors During Streaming

​SSE Keep-Alive Comments

​Stream Disconnection

​Error Handling Best Practices

​FAQ