This page will help you quickly identify and resolve common issues by providing detailed explanations for each error code. Please refer to this guide whenever you encounter an error, and follow the recommended steps for resolution.
Error response format
Errors returned by the API return a JSON body in the following shape:
Branch your error handling on code, not on message. The code value is a stable identifier, while the wording of message may change.
Some responses do not carry this body, so no code is available — a path that is rejected before routing, an unsupported HTTP method, or an error raised by the service that processes your request. Those rows are marked with — in the table below.
Error codes
| HTTP status | Error code | Cause | Possible solutions |
|---|---|---|---|
| 400 | invalid_request_body | Wrong format or data in request body, or a model that is invalid or no longer supported | For Solar APIs: • Check if the JSON syntax of the request body is correct • Check if all required keys exist in the request body • Check if the model parameter is included and refers to an available model • Check if all the keys in the request body are correct • Check if all the values in the request body are in correct types • Check if there is any typo! For Document AI APIs: • Check if the document file location is correct in the request body • Check if the document file is the supported file format • Check if the document file is 50MB (52,428,800 bytes) or smaller |
| 400 | invalid_path | The request URL contains invalid characters, such as a newline or other control characters | • Remove unintended characters from the path and query parameters |
| 401 | invalid_api_key | Invalid, deleted, or missing API key | • Check if you set API key in your request header • Check if Authorization header is in correct form - “Bearer API_KEY” • Check if your API Key is not deleted in Console • Check if there is any typo! |
| 401 | api_key_is_blocked | The API key itself is valid, but it has been blocked — most commonly because the account has no remaining credit and no registered payment method | • Register a payment method or purchase credit • Issuing a new API key does not resolve this error • If your payment method is already registered, contact support |
| 403 | api_key_is_not_allowed | API key suspended due to insufficient credit | • Register a payment method or purchase credit |
| 403 | studio_subscription_quota_exceeded | Your organization has used up its Studio usage. Returned when the request runs a Studio workflow, which draws on Studio usage instead of Console credit | • Check when usage resets on the usage page in your Studio organization settings • Subscribe to a plan or upgrade your current plan • On the Free plan usage resets the next day. See When usage runs out |
| 403 | data_residency_region_mismatch | Your organization is set to process data only in the Korea region, but the request was sent to an endpoint outside it, such as api.upstage.ai. Applies only to organizations approved for the Korea region | • Send the request to kr.api.upstage.ai instead. See Regional endpoints |
| 404 | invalid_path / — | Wrong URL path. Paths that do not match any endpoint are rejected before routing and return no JSON body | • Check if your request path is correct in the API reference |
| 405 | — | The HTTP method is not allowed for that endpoint, such as sending GET to a POST-only endpoint | • Check the HTTP method required by the endpoint • Requests sent to http:// are redirected to https:// with 301. If your client does not follow redirects, call https:// directly |
| 413 | payload_too_large | The request body is 500MB (500,000,000 bytes) or larger | • Reduce the size of the request body • Split the request into smaller ones |
| 413 | — | The uploaded document is larger than 50MB (52,428,800 bytes). Returned by the Document AI service | • Check if the document file is 50MB or smaller • Split the document into smaller files |
| 415 | — | Unsupported file format for the operation. Returned by the Document AI service | • Check if your file format is supported for conversion, split, or extraction • Use a supported file format |
| 422 | — | Document is damaged or corrupted. Returned by the Document AI service | • Check if the file is not corrupted or damaged • Try re-saving or re-exporting the file |
| 429 | too_many_requests | Exceeded the rate limit (RPM, TPM, or PPM). This includes too many tokens or pages, not only too many requests | • Check which rate limit was exceeded. Only the exceeded category returns an X-Upstage-RateLimit-Retry-After-* response header (-Requests, -Tokens, or -Pages) • Retry after the time in that header (Unix timestamp in seconds), and reduce the number of requests, tokens, or pages you send per time window • If you want to increase the rate limit, see How can I increase the rate limit, and are there any conditions required? |
| 429 | usage_limit_exceeded | The organization has reached its monthly postpaid billing limit. Usage covered by credits is excluded from the limit calculation. This is not a rate limit, so retrying alone does not help. | • Purchase credits, or have the Org Owner increase the monthly postpaid billing limit on the organization's Payment page. |
| 499 | client_closed_request | The client closed the connection before the response was complete, usually due to a client-side timeout or cancellation | • Increase the timeout of your HTTP client • Use streaming so that the first tokens arrive earlier • Check for a proxy or load balancer between your client and the API that may be cutting the connection |
| 500 | internal_server_error / unknown_error | There was an error while processing your request | • Retry your request after some time • Check status.upstage.ai for any ongoing service incidents • If you keep getting the error, please contact support |
| 503 | studio_subscription_gate_unavailable | The Studio subscription usage status could not be read for this request. Your quota is not necessarily exhausted | • Retry your request after a short wait • If the error persists, contact support |
| 503 | doorun_runtime_unavailable | The job runtime for a file collection import is temporarily unavailable. The import was not started | • Retry with the same Idempotency-Key to pick up the existing job instead of creating a duplicate • If the response includes a Retry-After header, wait that many seconds before retrying • Check status.upstage.ai for any ongoing service incidents |
| 502 / 503 | — | The request failed at the infrastructure layer before or after the API processed it | • Retry your request after some time • Check status.upstage.ai for any ongoing service incidents |
| 504 | gateway_timeout | The request did not complete within the gateway timeout | • Retry your request after some time • Reduce the size of the request, such as the number of pages or the length of the prompt • If you keep getting the error, please contact support |
401 api_key_is_blocked does not mean your API key is wrong. The key is valid, but it has been blocked — in most cases because the account has no remaining credit and no registered payment method. Issuing a new API key does not resolve it. Register a payment method to restore access, and contact support if the error persists afterward.