Errors and troubleshooting
Locate API issues by error source and HTTP status, then choose a safe recovery action.
When an API request fails, first save the HTTP status and a redacted error message. Then determine whether the problem comes from the request, authentication, the model, or the service. Do not repeatedly retry the same request before identifying the cause.
Protect credentials and customer data first
Troubleshooting records must not contain complete API keys, Authorization or x-api-key headers, cookies, passwords, complete prompts, customer files, or other sensitive information.
Identify where the error comes from
| Error source | Common symptoms | Recommended action |
|---|---|---|
| Request content | Invalid JSON, missing fields, incorrect parameter types, or unsupported file formats | Correct the request based on the error message; do not resend it unchanged |
| Authentication and permissions | The API key is missing or invalid, or the current key cannot access the target model | Check the Base URL, protocol-specific authentication headers, key status, and model permissions |
| Models and resources | The model ID, task ID, or request path does not exist | Copy the ID again from the model marketplace and confirm which account owns the resource |
| Platform or upstream service | The service is temporarily unavailable, processing times out, or the upstream service returns an error | Save diagnostic information and retry a limited number of times; stop sending requests if the problem persists |
| Asynchronous tasks | A submitted task fails, remains in progress for too long, or has no available result | Query the original task first instead of immediately creating a duplicate task |
A single failure can contain several clues. For example, 404 can mean that the endpoint is incorrect or that a model or task does not exist. Evaluate it together with the final request URL and error body.
HTTP status quick reference
| HTTP status | Common meaning | Recommended recovery |
|---|---|---|
400 | The request format, parameters, or input content is invalid | Correct the request, then send it again |
401 | The API key is missing or invalid, or the authentication header does not meet the endpoint requirements | Check the protocol's authentication method; create and replace the key if necessary |
403 | The current account, key, or model access does not satisfy the request | Check the account status, token restrictions, and model permissions |
404 | The Base URL, endpoint, model, or task does not exist | Verify the final URL, model ID, task ID, and owning account |
429 | Request rate, concurrency, quota, or service capacity is limited | Stop high-frequency requests, reduce the load based on the error details, and retry later |
500–599 | The platform, gateway, or upstream service temporarily cannot complete the request | Save diagnostic information and use a limited number of retries with backoff |
These statuses provide only an initial direction. Program error codes can differ between protocols and upstream services, so determine the cause from the HTTP status, the actual error body, and the corresponding API Reference.
Recommended troubleshooting process
Record the failure
Save the request time and time zone, Method, Path, model ID, HTTP status, and a redacted, length-limited error message. If the response contains a Request ID, save it as well.
Verify the address and authentication
Use https://api.agtcloud.cn/v1 as the Base URL and confirm that the final URL does not contain a duplicated /v1/v1. OpenAI-compatible endpoints usually use Authorization: Bearer your-api-key; for other protocols, check the authentication headers required by the corresponding Reference.
Verify the model and request content
Confirm that the model ID comes from the models visible to the current account. Then check Content-Type, JSON, required fields, file type, and input size.
Decide whether to retry
Fix 400, 401, 403, and confirmed missing-resource errors before retrying. Temporary network or 5xx failures can be retried a limited number of times with progressively longer waits.
Prepare redacted information
If the issue persists, prepare minimal reproduction steps and diagnostic information. Do not copy complete keys, customer prompts, files, or unredacted responses for troubleshooting.
Retry safely
- For temporary failures on ordinary read-only requests, use a limited number of retries with backoff.
- Resend requests with parameter, authentication, or permission problems only after fixing the cause.
- Before resending a task-creation request, external tool call, or another request that can have side effects, confirm whether the original request already took effect.
- For asynchronous requests, query the original task ID first instead of creating a duplicate task only because the client timed out.
- Set a maximum retry count and total wait time. Stop automated requests and preserve diagnostic information if the failure continues.
Troubleshooting information to prepare
| Information | Example or description |
|---|---|
| Time of occurrence | Include the date, time, and time zone |
| Request location | Method and Path, without the complete API key |
| Request target | Model ID; asynchronous tasks can also include the task ID |
| Response result | HTTP status and redacted error information |
| Request characteristics | Whether it streams, includes tools, or creates an asynchronous task |
| Client environment | SDK name and version, runtime version, and minimal reproduction steps |
| Tracing information | Save the Request ID when the response contains one |
For program error codes and handling guidance, see the Error code reference. If the issue remains unresolved, continue with Request ID and the FAQ. For initial integration issues, review Quickstart and API keys and authentication.