# Errors and retries

Check request status and safely retry the original action.

## 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](/docs/api) 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.