400 Bad Request | The request format or parameters are invalid, such as malformed JSON, wrong field types, out-of-range model parameters, or a body that does not match the endpoint | Check the request body, Content-Type, model name, and parameters; retry with a minimal request |
401 Unauthorized | The API key is missing, invalid, or the Authorization: Bearer header is malformed | Confirm the request includes Authorization: Bearer sk-... and that the key is not deleted or disabled |
403 Forbidden | The account or key cannot complete the request, often because of insufficient balance, exhausted key quota, key expiration, model restrictions, or IP restrictions | Check balance, key quota, expiration, model permissions, and IP restrictions |
404 Not Found | The endpoint path, Base URL, or model name is wrong | Confirm the Base URL, endpoint path, and model name; copy model names from Model Square when possible |
408 Request Timeout | The request did not complete within the allowed time | Shorten the input, reduce attachments or output length, then retry; you can also switch to a faster model |
413 Payload Too Large | The request body, attachment, or context is too large | Compress files, split content, shorten context, or send fewer attachments in one request |
415 Unsupported Media Type | The Content-Type or uploaded file format is unsupported | Set the required Content-Type and confirm the file format is supported by the selected capability |
422 Unprocessable Entity | The request can be parsed, but its content is not valid for the endpoint or model | Check message structure, tool calls, image count, file type, and model capability |
429 Too Many Requests | Requests are too frequent, concurrency is too high, or a rate limit was reached | Lower concurrency, increase retry intervals, and use exponential backoff |
500 Internal Server Error | The service hit an exception while processing the request, or the model response could not be handled normally | Retry later; if it continues, keep the request time, model name, and error message for support |
502 Bad Gateway | A service in the request path returned an abnormal response | Retry once; if it repeats, switch models and keep the failed record |
503 Service Unavailable | The selected model or service is temporarily unavailable, such as busy routes, no available route, or maintenance | Retry later or switch to another available model |
504 Gateway Timeout | The model response timed out | Shorten the input, lower max output length, reduce attachments, or switch models |
