Errors and retries
Check request status and safely retry the original action.
Select an endpoint to edit a request and view its response.
Read the response
Errors include a code and request_id. Keep both when troubleshooting. A 202 response means accepted; use the returned ID to check completion.
| Status | What to do |
|---|---|
401 |
Check whether the key is valid, expired or revoked |
403 |
Check base access, scopes, allowed IPs and spending policy |
404 |
Check the ID and whether it belongs to this workspace |
409 |
Refresh the resource or quote before deciding your next action |
422 |
Correct the request fields; check the error code |
429 |
Wait for Retry-After before sending another request |
5xx or no response |
Check the original operation before retrying a write |
Retry the same action
For endpoints requiring Idempotency-Key, generate one key for a new action and save it with the exact request body. Reuse both when retrying. A successful replay returns the original result and preserves the original charge.
Keep the original key when a response times out. Changing the body while keeping the key causes a conflict. Check the API reference to see which endpoints require the header.
A traffic purchase needs attention
DYNAMIC_GRANT_FAILED or DYNAMIC_GRANT_UNKNOWN can include the purchase receipt. Read GET/dynamic/purchases/{id} and contact support with that ID. Repeating the purchase request with its original key returns the original result.
Support can review the purchase, retry eligible activations, and cancel and refund eligible failed purchases.
Respect request limits
Each key allows up to 120 requests per minute. Use the response's Retry-After value after a 429, and slow status polling when nothing changes. Webhooks can replace frequent polling for supported events.
Keep values exact
Money is an integer string in CNY fen. Use integer arithmetic or a decimal library. Timestamps use UTC. An unavailable balance is null. Read each page of a paginated list to collect the complete result.