API ResourcesErrors

Error Codes

This guide explains how to diagnose API failures using common status codes, error types, and recommended troubleshooting steps.

You can determine whether a request was successful by checking the status code in the API response. If the response indicates a failed request, you can identify the issue based on the error type and message, and perform initial debugging before contacting support.

Before contacting support, record the Request ID, timestamp, endpoint, model, and complete error type. Remove API keys, Authorization headers, and other sensitive information.

Status Codes

Below is a list of different status code categories returned by the OriginRouter API. You can use these status codes to determine whether a request was successful.

Name
2xx
Optional
Optional
Description
2xx status codes indicate the request was successful.
Name
4xx
Optional
Optional
Description
4xx status codes indicate a client error — meaning the problem is on your side.
Name
5xx
Optional
Optional
Description
5xx status codes indicate a server error — you typically won't encounter these.

Error Types

Whenever a request fails, the OriginRouter API returns a response containing an error type and error message. You can use this information to better understand the issue and find a solution. Most error messages are fairly intuitive and actionable.

The following are the error types supported by the OriginRouter API — understanding these can help you identify where the problem lies.

Some error responses use two-level error codes: the top-level code identifies a stable error category, while details.code describes the specific reason. Use details.request_id when contacting support so the corresponding server logs can be located. Error responses without details.code can continue to be handled using the top-level code.

Name
request_error
Optional
Optional
Description
The request content, format, or size is invalid. The details.code identifies the specific reason, such as request_too_large.
Name
rate_limit_error
Optional
Optional
Description
The request was limited by rate, concurrency, or an upstream service. The details.code identifies the specific reason, such as rate_limited.
Name
upstream_error
Optional
Optional
Description
The model service did not succeed after automatic node retries. Detailed codes include upstream_timeout, upstream_overloaded, upstream_unavailable, and all_providers_failed.
Name
internal_server_error
Optional
Optional
Description
An internal gateway error occurred, or multiple upstream services returned failures that could not be classified consistently. Detailed codes include upstream_authentication_failed, unknown_upstream_error, and all_providers_failed. Provide details.request_id when contacting support.

Name
400 missing_parameter
Optional
Optional
Description
A required parameter is missing from the request. Please check and ensure all necessary fields are included, and refer to the API documentation for the corresponding endpoint.
Name
400 unsupported_parameter
Optional
Optional
Description
The request contains a parameter that is not applicable to the current model. Please check and remove the parameter, or refer to the API documentation to confirm the valid parameter list supported by your selected model.
Name
400 invalid_parameter_type
Optional
Optional
Description
Incorrect parameter type. Please refer to the parameter type description for the corresponding endpoint in the API documentation.
Name
400 invalid_parameter_value
Optional
Optional
Description
Invalid parameter value. While the parameter type is correct, its specific value does not meet expectations. Please refer to the API documentation to correct it.
Name
400 invalid_parameter_combination
Optional
Optional
Description
Invalid parameter combination. The server detected conflicts or incompatibility between parameters. Please refer to the API documentation to adjust the parameter combination.
Name
4xx llm_request_failed
Optional
Optional
Description
The model provider returned a client error (4xx). This usually indicates issues with request parameters, such as invalid model name, missing required fields, incorrect format, or exceeding limits. Please check and correct the request based on the specific error information returned.
Name
401 unauthenticated
Optional
Optional
Description
Authentication credentials were not provided or are invalid. Please ensure the 'Authorization' header is correctly set and valid credentials are used.
Name
401 api_key_expired
Optional
Optional
Description
This API key has expired. Please replace it with a new valid key.
Name
402 insufficient_funds
Optional
Optional
Description
Your paid account balance is insufficient to use this model. Please recharge promptly.
Name
402 account_arrears
Optional
Optional
Description
Your account is currently in arrears and the service has been suspended. Please recharge to restore service.
Name
402 paid_balance_zero_free_not_accepted
Optional
Optional
Description
Your paid balance is zero. While you may have free credits, they do not apply to this model. Please recharge your paid balance.
Name
402 free_balance_zero_paid_not_accepted
Optional
Optional
Description
Your free balance is zero. While you may have a paid balance, it does not apply to this model. Please wait for the free credits to update or check the payment options for this model.
Name
402 insufficient_balance_for_premium_model
Optional
Optional
Description
Your paid account balance is below the minimum threshold required for this premium model, so the request was rejected.
Name
402 subscription_quota_exceeded
Optional
Optional
Description
Your subscription quota has been exceeded. This usually occurs when your current usage exceeds the daily or weekly limit of your subscription. Please enable balance fallback or upgrade your plan.
Name
403 api_key_not_active
Optional
Optional
Description
This API key is currently inactive. Please activate it first.
Name
403 api_key_suspended
Optional
Optional
Description
This API key has been suspended. If you believe this is an error, please contact support.
Name
403 api_key_revoked
Optional
Optional
Description
This API key has been revoked and can no longer be used.
Name
403 permission_denied
Optional
Optional
Description
You do not have permission to access this resource.
Name
403 subscription_permission_denied
Optional
Optional
Description
Your current subscription plan does not have permission to call this model. Please upgrade your subscription plan to access this model.
Name
403 subscription_feature_unauthorized
Optional
Optional
Description
Your current subscription plan does not support calling this API endpoint. Please check your plan benefits or upgrade to a premium subscription that includes this feature to unlock access.
Name
403 ip_access_denied
Optional
Optional
Description
Your IP address has been blocked by the system's security policy. Access denied. If you believe this is a false positive, please contact support.
Name
403 memory_quota_exceeded
Optional
Optional
Description
Memory creation has reached its limit. The number of memory sessions allowed by your current plan is full. Please upgrade your plan or delete old memory sessions to continue.
Name
404 invalid_model
Optional
Optional
Description
Invalid model name. This model ID does not exist. Please ensure you are using the correct and published model ID.
Name
404 unsupported_model_for_endpoint
Optional
Optional
Description
The model exists but is not supported by the current endpoint. Please refer to the relevant model list for compatible model information.
Name
404 invalid_model_origin
Optional
Optional
Description
Invalid model provider. This model provider does not exist. Please ensure you are using the correct model provider or model ID.
Name
404 memory_not_found
Optional
Optional
Description
The specified memory ID does not exist. The system cannot find a memory session associated with this ID. Please confirm whether the ID was entered correctly or if the memory has been deleted.
Name
422 fallback_step_timeout_exceeded
Optional
Optional
Description
Request terminated: The current step execution time exceeded the timeout_ms limit you specified in the fallback configuration.
Name
422 fallback_global_timeout_exceeded
Optional
Optional
Description
Request terminated: The total execution time exceeded the global_timeout_ms limit you specified in the fallback configuration.
Name
422 fallback_config_max_retries_reached
Optional
Optional
Description
Request terminated: The total number of model attempts reached the max_total_retries limit you specified in the fallback configuration.
Name
429 concurrency_limit_exceeded
Optional
Optional
Description
The number of your current concurrent requests exceeds the limit. Please retry later or optimize your request frequency.
Name
429 excessive_error_rate
Optional
Optional
Description
This API key has generated too many erroneous requests in a short period and has been temporarily restricted. Please check your code logic and fix the request errors before retrying.
Name
500 internal_server_error
Optional
Optional
Description
An unexpected internal error occurred while processing your request. Please retry later. If the problem persists, please contact technical support.
Name
500 balance_retrieval_failed
Optional
Optional
Description
An internal error occurred while the system was retrieving user balance.
Name
500 images_description_error
Optional
Optional
Description
An unexpected internal error occurred when the system was processing and describing your images. Please retry later or contact technical support.
Name
500 files_description_error
Optional
Optional
Description
An unexpected internal error occurred when the system was processing and describing your files. Please retry later or contact technical support.
Name
500 llm_convert_failed
Optional
Optional
Description
The system encountered an error when processing content returned by the model provider. Although the model service provider may have successfully returned content, processing failed due to some unexpected situation. Please modify request parameters, retry later, or contact technical support.
Name
500 memory_service_failed
Optional
Optional
Description
Internal error in the memory service. The system encountered unexpected issues when processing memory storage or retrieval. Please retry later. If the problem persists, contact technical support. For detailed error information, see here.
Name
5xx llm_request_failed
Optional
Optional
Description
The model provider returned a server error (5xx). This is usually a temporary issue on the provider's side, such as system overload, service unavailability, or internal errors. Please retry later, or check the provider's status page to confirm if there are any service disruptions.
Name
503 gemini_service_busy
Optional
Optional
Description
The model provider's service is currently busy and cannot process requests. This is usually caused by high concurrent requests, resource limitations, or system maintenance. Please retry later, or check the provider's status page to confirm if there are any known issues or maintenance work.

Error Response Example

{
  "code": "invalid_model",
  "message": "Unsupported models.",
  "details": "The specified model is not supported. Please check all available models at https://originrouter.com/console#models."
}

Error Types (Memory)

When processing memory module-related requests, when specific business logic errors occur, the OriginRouter API returns standard HTTP status codes and also provides corresponding internal error codes in the details object of the response body. These error codes are used for more precise identification of failure reasons, distinguishing between quota limits, invalid identifiers, and underlying service exceptions. By parsing details.code, developers can implement more targeted exception handling and recovery logic.

Name
400 missing_parameter_user_id
Optional
Optional
Description
The user_id parameter is missing or has an incorrect type. user_id must be a non-empty string.
Name
400 missing_parameter_run_id
Optional
Optional
Description
The run_id parameter is missing or has an incorrect type. run_id must be a non-empty string used to identify a unique session ID.
Name
400 missing_parameter_token
Optional
Optional
Description
The token parameter is missing. When executing a callback, you must provide the execute_callback_token returned by the Search interface.
Name
400 invalid_parameter_personal_memory
Optional
Optional
Description
The personal_memory parameter is invalid. This parameter must be a Boolean value, used to indicate whether to enable personalized memory retrieval.
Name
400 invalid_param_memory_mode
Optional
Optional
Description
The memory_mode parameter is invalid. Only 'read_only' or 'read_write' modes are supported.
Name
400 invalid_param_execution_mode
Optional
Optional
Description
The execution_mode parameter is invalid. Only 'sync' (synchronous) or 'async_with_callback' (asynchronous callback) modes are supported.
Name
400 execution_mode_conflict
Optional
Optional
Description
Execution mode conflicts with memory mode. The async_with_callback mode is only allowed in read_write memory mode.
Name
400 invalid_messages_format
Optional
Optional
Description
The messages parameter format is invalid. This parameter must be a non-empty List containing message objects in OpenAI format.
Name
400 invalid_param_history_window
Optional
Optional
Description
The history_window parameter is invalid. It must be an integer greater than 0, used to specify the number of conversation turns to retain in context.
Name
400 invalid_param_summary_window
Optional
Optional
Description
The summary_window parameter is invalid. It must be an integer greater than or equal to 5, used to specify the window length that triggers summary generation.
Name
400 token_invalid_or_expired
Optional
Optional
Description
The provided token is invalid or expired. Please ensure you are using the latest token and completing the callback within the validity period.
Name
400 invalid_window_config
Optional
Optional
Description
The window configuration during callback is invalid. This is usually due to passing an incorrect summary_window parameter.
Name
400 invalid_messages_start_role
Optional
Optional
Description
Message sequence role error. The message list submitted to the callback interface must start with the user role.
Name
400 invalid_messages_group_count
Optional
Optional
Description
Message group count error. The callback interface only allows submitting one complete conversation group (User -> Assistant) at a time.
Name
400 invalid_messages_role_sequence
Optional
Optional
Description
Message sequence structure error. The submitted conversation group must strictly follow the order of "starting with User and ending with Assistant".
Name
400 invalid_history_structure_en
Optional
Optional
Description
Message sequence structure error. Each conversation group in the submitted message history (except for the latest current turn) must be in a complete closed state.
Although the OpenAI API format allows consecutive user messages or incomplete intermediate states, to ensure that the memory system can accurately perform logical segmentation and vectorization of the context, this system strictly requires that historical data follow the "request-response" pairing principle:
- Regular conversation: Each historical user message must be immediately followed by an assistant message as the ending.
- Tool calling: If Function Calling is involved, the historical record must contain a complete calling loop (i.e., assistant initiates the call; tool returns the result; assistant finally summarizes). It is not allowed to end a history group with a tool message or an assistant message that only contains tool_calls.
Name
404 history_not_found
Optional
Optional
Description
The historical record for the specified session was not found. This may be because the run_id does not exist, or the session has not been initialized yet.
Name
409 history_integrity_error_en
Optional
Optional
Description
Historical record fork detected. The system detected that the context submitted by the client is inconsistent with the server storage.
Rule description:
1. Append only: For user and assistant messages, you must perform full or sliding window matching based on the server's existing history. It is strictly forbidden to modify historical content or skip intermediate messages.
2. Special exemption: system and developer messages are not involved in consistency verification.
Example (server has message records [A, B]): Allowed: [System, B, C] (sliding match) or [System, C] (pure incremental); Rejected: [System, A, C] (discontinuous) or modified A's content.
Name
409 callback_state_mismatch
Optional
Optional
Description
Callback state mismatch. The submitted message group ID does not match the last_group_id expected by the server, usually due to state misalignment caused by concurrent requests.
Name
423 resource_locked_summary_generation
Optional
Optional
Description
Resource locked. The summary generation of the previous conversation turn is still in progress (Status=1). Please retry later.
Name
423 resource_locked_memory_embedding
Optional
Optional
Description
Resource locked. The vector embedding (Embedding) processing of the new message is still in progress, and the memory database is not ready yet. Please retry later.
Name
429 concurrency_limit_exceeded_write
Optional
Optional
Description
Write concurrency limit exceeded. The current session (User:RunID) is undergoing a write operation, and only one write request is allowed at the same time.
Name
429 concurrency_limit_exceeded_read
Optional
Optional
Description
Read concurrency limit exceeded. The number of concurrent read requests for the current session has reached the upper limit (default 5). Please reduce the request frequency.
Name
429 concurrency_limit_exceeded
Optional
Optional
Description
Callback concurrency limit exceeded. The callback operation for the current session has been locked. Please retry later.
Name
500 internal_error
Optional
Optional
Description
Internal server error. An unexpected error occurred when the system was generating the execution token (Token).
Name
500 memory_delete_error
Optional
Optional
Description
Memory deletion failed. An uncaught exception occurred when attempting to delete memory from the vector database or graph database.
Name
500 network_error
Optional
Optional
Description
Memory service network connection error. Please retry later. If the problem persists, please contact technical support.

Error Response Example

{
  "error": {
    "code": "memory_service_failed",
    "message": "An internal error occurred in the Memory service. Retry the request later.",
    "details": {
      "status_code": 403,
      "code": "memory_quota_exceeded"
    }
  }
}