Errors
TokenBay Gateway error response format, HTTP status code, and business error code reference
This page defines the error response format for TokenBay Gateway business APIs and documents the conventions for HTTP status codes and business error codes.
HTTP status codes identify request processing and service availability outcomes; specific business failure reasons are returned in error.code.
For asynchronous task APIs, task results and progress are represented by endpoint-specific response fields.
Error Response Format
Response
schemaerror.messagestringOptionalError message for the caller.
error.typestringOptionalError category.
error.codestringOptionalBusiness or protocol error code.
HTTP Status Code Conventions
Errors
| Status | Meaning | Typical Scenario |
|---|---|---|
| 200 | Success | Task query succeeded. Even if the task itself failed, it is represented by status: "failed" in the response body. |
| 400 | Client Request Error | Invalid parameters, missing required fields, request body parsing failure, or task not found. |
| 401 | Authentication Failed | Token is missing or invalid. |
| 403 | Insufficient Permissions | User is banned, quota is insufficient, access to the group or model is not allowed, or IP restrictions do not pass. |
| 404 | Resource Not Found | No route matched, or the task does not exist in the video content proxy. |
| 413 | Payload Too Large | The request body exceeds the size limit. |
| 429 | Rate Limited | Model request rate limit, global API rate limit, or upstream load saturation. |
| 500 | Internal Server Error | Request conversion failed, upstream invocation failed, response parsing failed, or serialization failed. |
| 501 | Not Implemented | The interface or conversion is not implemented. |
| 502 | Bad Gateway | The upstream URL fetch failed in the video content proxy. |
| 503 | Service Unavailable | No available channel, system resource overload (CPU / memory / disk), or no available key in the channel. |
| 504 | Upstream Timeout | The channel response time exceeded the timeout limit. |
HTTP status codes identify request processing and service availability outcomes; specific business failure reasons are returned in error.code.
Business Error Codes
Errors
| Status | Code | Meaning |
|---|---|---|
| 403 | api_key_disabled | API key is disabled |
| 403 | api_key_expired | API key has expired |
| 403 | api_key_unavailable | API key status is unavailable |
| 403 | ip_denied_by_blacklist | Source IP matched the blacklist |
| 403 | ip_not_in_whitelist | Source IP is not in the whitelist |
| 403 | model_disabled | Model is disabled |
| 403 | model_capability_not_supported | Model does not support the requested endpoint capability |
| 403 | api_key_model_not_allowed | API key model allowlist or denylist does not permit this model |
| 403 | account_point_insufficient | Account point balance is insufficient |
| 403 | api_key_point_insufficient | API key sub-quota is insufficient |
| 403 | access_rule_time_window_denied | Request is outside the allowed access-rule time window |
| 404 | model_not_found | Model does not exist |
| 429 | account_rate_limited | Account request rate limit exceeded |
| 429 | api_key_point_limit_exceeded | API key periodic point limit exceeded |
Business error codes are returned in error.code to identify specific business failure causes and support client-side classification and handling.