> For the complete documentation index, see [llms.txt](https://docs.apismart.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apismart.ai/troubleshooting/http-status-codes-and-api-errors.md). # HTTP Status Codes and API Errors Understand ApiSmart HTTP status codes, API error codes, common causes, and recommended handling and retry strategies. ApiSmart uses standard HTTP status codes together with API-specific error codes to indicate whether a request succeeded and, if not, what caused the failure. When handling errors, check the **HTTP status code first**, then use the returned error `code` and message for more detailed diagnostics. Some model providers may return additional error codes over time, so your application should also handle unknown error codes gracefully. ### 🚦 Error Handling at a Glance | HTTP Status | Category | Retry? | | ----------- | -------------------------------- | -------------------------- | | `400` | Invalid request or parameters | No — fix the request first | | `401` | Authentication failed | No — check the API Key | | `402` | Insufficient balance | No — add funds first | | `403` | Access or model capability issue | Usually no | | `404` | Task or resource not found | Usually no | | `410` | Video result unavailable | Usually no | | `429` | Rate limit exceeded | Yes — wait before retrying | | `500` | Internal server error | Yes — retry cautiously | | `502` | Gateway or upstream error | Usually yes | | `503` | Temporary service unavailable | Yes | | `504` | Gateway timeout | Yes | Do not automatically retry every failed request. Authentication errors, invalid parameters, unsupported resolutions, and access errors should normally be corrected before another request is sent. ### 400 — Bad Request A `400` response means the request could not be processed because its parameters or format are invalid. Possible error codes include: | Code | Meaning | | ------------------------ | --------------------------------------------------------- | | `invalid_request_error` | Required parameters are missing or the request is invalid | | `invalid_json` | The JSON request body is malformed | | `unsupported_resolution` | The requested resolution is not supported | | `InvalidParameter` | A parameter was rejected by the underlying model service | #### How to Troubleshoot Check: * Required request parameters * JSON syntax * Parameter types and values * Model-specific parameter requirements * Supported image or video resolutions * Input asset limits and formats Do not repeatedly retry the same request without correcting the invalid parameter. ### 401 — Invalid API Key Possible error code: `invalid_api_key` The API Key used to authenticate the request is invalid. Verify that the request contains: ```http Authorization: Bearer ``` Check that: * The API Key is correct * The API Key has not been deleted or disabled * The `Bearer` prefix is present * There are no extra spaces or missing characters * Your application is using the intended environment variable Never expose your full API Key in screenshots, logs, public repositories, or support requests. For API Key management, see [**Create and Manage API Keys**](/welcome-to-apismart/api-keys/create-and-manage-api-keys.md). ### 402 — Insufficient Balance Possible error code: `insufficient_quota` This means the account does not have sufficient available balance to complete the request. Before retrying: 1. Check your current wallet balance. 2. Review recent usage and costs. 3. Add funds if necessary. 4. Retry the request after sufficient balance becomes available. See [**Add Funds and Understand Wallet Credits**](/account-and-wallet/add-funds-and-understand-wallet-credits.md) and [**Usage Logs and Costs**](/api-usage/usage-logs-and-costs.md) for more information. ### 403 — Access and Model Errors A `403` response means the request was authenticated, but the requested model, endpoint, or resource cannot be used in the current context. #### `model_not_allowed` The selected model is not available to your API Key or account. Check the currently available models with: ```bash curl https://gw.apismart.ai/v1/models \ -H "Authorization: Bearer " ``` Use the returned `data[].id` exactly as provided. #### `model_not_image_capable` The selected model cannot be used with the Image Generation API. Choose a supported image model instead. #### `model_not_video_capable` The selected model cannot be used with the Video Generation API. Choose a supported video model instead. #### `AccessDenied` Access to the selected model or operation was denied. Verify that the model and API endpoint are supported for your account and request. #### `asset_not_owned` A video request references an `asset://` resource that does not belong to the current account. Requests rejected with this error do **not** incur a generation charge. Use only verified assets associated with the account making the request. ### 404 — Resource Not Found ApiSmart uses different `404` errors depending on the resource being accessed. #### `task_not_found` The requested video task does not exist. Check: * The task ID is correct * You are querying the intended task * The ID was stored correctly after task creation Video task status is queried with: ``` GET /v1/video/tasks/{id} ``` #### `resource_not_found` A real-person asset operation refers to a resource or asset group that: * Does not exist, or * Does not belong to the current account Verify the asset or group identifier and account ownership before retrying. ### 410 — Video Not Available Possible error code: `video_not_available` The requested video result is no longer available, or the associated video task did not complete successfully. When this occurs, check the original video task: ``` GET /v1/video/tasks/{id} ``` Confirm whether its final status was: * `succeeded` * `failed` * `cancelled` * `expired` Do not assume that every created video task will have downloadable video content. For video task behavior, see [**Video Generation API**](/api-guides/video-generation-api.md). ### 429 — Rate Limit Exceeded Possible error code: `rate_limit_error` A `429` response means the service rate limit has been reached. Do not send repeated immediate retries. Instead: * Reduce request frequency * Add a delay before retrying * Use exponential backoff * Avoid creating retry loops that generate additional traffic A simple backoff sequence might be: ``` 1 second → 2 seconds → 4 seconds → 8 seconds ``` Your application should stop retrying after a reasonable number of attempts. ### 500 — Internal Server Error Possible error codes include: * `internal_error` * `InternalServerError` These indicate an internal service error. Unlike a `400` request error, a `500` response may be temporary. Recommended handling: 1. Keep the original Request ID when available. 2. Wait briefly. 3. Retry with exponential backoff. 4. Stop after a limited number of attempts. 5. Contact ApiSmart Support if the problem continues. Avoid unlimited automatic retries. ### 502 — Gateway or Upstream Error Possible errors can include: * `proxy_error` * `BadGateway` A `502` generally indicates a temporary problem between ApiSmart and an upstream model service or network layer. Use exponential backoff before retrying. #### Special Case: Real-Person Verification When using the Seedance verified real-person asset workflow, a verification-result request can return: `502 upstream_error` while the user has **not yet completed the mobile verification process**. In this specific workflow, the response does not necessarily indicate a platform failure. Complete the verification through the provided `H5Link` before retrieving the result again. If polling is required, use an interval of approximately **5–10 seconds** and keep the total polling period within the validity period of the verification token. This special behavior applies to the real-person verification workflow and should not be treated as the general meaning of every `502` response. ### 503 — Service Temporarily Unavailable Possible error codes include: | Code | Meaning | | --------------------------------- | ---------------------------------------------------------- | | `provider_not_available` | The model provider is temporarily unavailable | | `quota_service_unavailable` | The quota or balance service is temporarily unavailable | | `proxy_unavailable` | The proxy or gateway dependency is temporarily unavailable | | `asset_owner_service_unavailable` | The asset ownership service is temporarily unavailable | These errors normally indicate a temporary dependent-service problem. When appropriate: 1. Check the response for `Retry-After`. 2. Wait for the specified period when provided. 3. Retry using exponential backoff. 4. Limit the total number of retries. If a `503` appears after changing a model ID, also verify that the model ID matches the documented value exactly. ### 504 — Gateway Timeout Possible error code: `GatewayTimeout` A `504` means a gateway or upstream service did not respond in time. This can be temporary. Recommended handling: * Wait before retrying * Use exponential backoff * Avoid immediate repeated requests * Review your own client timeout settings where applicable For synchronous image generation, your client should allow sufficient time for the generation request to complete. ### 🔁 Retry Strategy Errors can generally be divided into two groups. #### Fix Before Retrying Usually do not automatically retry: * `400` * `401` * `402` * Most `403` * Most `404` * `410` These errors generally require a request, authentication, balance, access, or resource issue to be corrected first. #### Retry Temporary Failures A controlled retry strategy can be appropriate for: * `429` * `500` * `502` * `503` * `504` Use exponential backoff instead of retrying immediately. For example: ``` Attempt 1 → wait 1 second Attempt 2 → wait 2 seconds Attempt 3 → wait 4 seconds Attempt 4 → wait 8 seconds ``` If the server provides a `Retry-After` value, follow it where applicable. Always place a limit on retries. ### 🧩 Handle Unknown Error Codes Some error responses may contain codes returned by the underlying model provider. These values may change or new codes may appear as provider services evolve. Do not build your application so that it only works with a fixed list of known error codes. Recommended logic: 1. Check the HTTP status code. 2. Read the returned API error code when available. 3. Use the HTTP status to decide the general handling strategy. 4. Log unknown error codes for diagnostics. 5. Preserve the original error message and Request ID when available. 6. Avoid treating an unknown error code as a successful request. HTTP status codes should be the primary signal for determining whether a request should be corrected or retried. ### 🔎 Troubleshooting with Request IDs When investigating a failed API call, keep the **Request ID** associated with the request when available. You can also review the corresponding record in [**Usage Logs and Costs**](/api-usage/usage-logs-and-costs.md). Useful troubleshooting information can include: * Request ID * Request time * Model * API endpoint * HTTP status * Error code * Error message If you contact ApiSmart Support, provide the relevant Request ID and error information. **Never provide your full API Key to support.** ### 📋 Error Code Reference | HTTP Status | Error Code | Description | | ----------- | --------------------------------- | ------------------------------------------------------------------------------ | | `400` | `invalid_request_error` | Missing or invalid request parameters | | `400` | `invalid_json` | Invalid JSON request body | | `400` | `unsupported_resolution` | Resolution is not supported | | `400` | `InvalidParameter` | Model service rejected a parameter | | `401` | `invalid_api_key` | Invalid API Key | | `402` | `insufficient_quota` | Insufficient account balance | | `403` | `model_not_allowed` | Model is not available | | `403` | `model_not_image_capable` | Model does not support the image endpoint | | `403` | `model_not_video_capable` | Model does not support the video endpoint | | `403` | `AccessDenied` | Access to the model or operation was denied | | `403` | `asset_not_owned` | Referenced real-person asset is not owned by the account | | `404` | `task_not_found` | Video task does not exist | | `404` | `resource_not_found` | Real-person asset or asset group does not exist or is not owned by the account | | `410` | `video_not_available` | Video task was unsuccessful or the result is unavailable | | `429` | `rate_limit_error` | Service rate limit exceeded | | `500` | `internal_error` | Internal server error | | `500` | `InternalServerError` | Internal server error | | `502` | `proxy_error` | Model service or network-layer error | | `502` | `BadGateway` | Upstream gateway error | | `502`\* | `upstream_error` | Special verification-state response in the real-person workflow | | `503` | `provider_not_available` | Model provider temporarily unavailable | | `503` | `quota_service_unavailable` | Quota service temporarily unavailable | | `503` | `proxy_unavailable` | Proxy dependency temporarily unavailable | | `503` | `asset_owner_service_unavailable` | Asset ownership service temporarily unavailable | | `504` | `GatewayTimeout` | Upstream service timed out | \* `upstream_error` is documented specifically for the real-person verification flow while verification has not yet been completed. ### ✅ Error Handling Checklist Before treating an API request as permanently failed: * Check the HTTP status code * Read the returned error code and message * Confirm that the API Key is valid * Verify the model ID * Verify that the model supports the endpoint * Check required request parameters * Check your available balance * Review model-specific resolution and input requirements * Retry temporary `5xx` or `429` errors only with controlled backoff * Preserve the Request ID for troubleshooting * Handle unknown error codes gracefully ### ➡️ Next Steps Continue with: * [**Models and Model IDs**](/models-and-pricing/models-and-model-ids.md) — Verify model IDs and availability * [**Usage Logs and Costs**](/api-usage/usage-logs-and-costs.md) — Investigate request-level errors and costs * [**Create and Manage API Keys**](/welcome-to-apismart/api-keys/create-and-manage-api-keys.md) — Manage authentication credentials * [**Balance and Usage Limit Issues**](/troubleshooting/balance-and-usage-limit-issues.md) — Troubleshoot balance-related failures