Handle errors and uncertain outcomes

Check both the HTTP status and the JSON response. AntAPI uses a code, data, and error envelope. Successful requests use code 0 and an empty error string; data is the endpoint-specific payload. Failures use a stable nonzero code and a human-readable error. Do not branch on translated error text.

This is an illustrative envelope only, not a complete product response:

{
  "code": 0,
  "data": {},
  "error": ""
}

Use the generated API Reference for endpoint-specific payloads and errors. An HTTP 202 is an accepted asynchronous operation. An HTTP 200 result page can contain failed or inconclusive items; inspect the individual item fields.

Choose a recovery action

HTTP status	What to check	What to do
400	Request shape, input, or parameters.	Correct the input before trying again.
401	Missing, invalid, revoked, or unavailable project credentials.	Check the key and organization/project state.
402	Eligible Credits or reservation requirements.	Check Credits and the maximum cost of the operation.
404	Published route or resource identity in the current project scope.	Verify the path, job ID, and project.
409	Changed input under the same key, or original operation still in progress.	Read the error; keep the original key for an unchanged retry.
429	Request rate or concurrency limits.	Reduce concurrency and back off; honor Retry-After when provided.
502	Upstream connection or response safety failure.	Treat execution as potentially uncertain and preserve the original operation identity.
503	Published snapshot or settlement temporarily unavailable.	Back off and retry the same logical operation.
504	Upstream timeout.	Do not assume no work ran; recover using the original key or job ID.

Product-specific errors can provide more detail than this Gateway overview. Use the product guide for its source availability and item outcome semantics; an inconclusive result does not establish a successful item.

When the outcome is unknown

If a batch create request times out before you receive a job ID, repeat the same POST with its saved Idempotency-Key, body, and query. If you already have the job ID, use progress and result requests. These reads do not create another batch or add lookup charges.

For synchronous calls, a stable idempotency key preserves the recorded financial outcome, but does not guarantee that the original response body can be replayed. Do not silently create a new paid operation just to recover a lost body.

The platform keeps the original reservation while it recovers authorized execution. Client disconnection and HTTP timeout do not cancel work. Cancellation stops future batch work; successful items can still settle.

Collect useful diagnostics

Record the HTTP status, stable error code, X-Request-ID, timestamp, and batch job ID where available. Check the matching usage and receipt records in Console. Remove Authorization headers, API keys, cookies, request bodies, and sensitive result data from shared diagnostics.