Documentation / Errors & retries · Updated 16 September 2026
Handle the unexpected.
API responses include an X-Request-Id header. Application errors use the following envelope. Cloudflare or the hosting edge can return a different response before the request reaches the application; handle non-JSON errors safely.
{
"error": {
"code": "invalid_request",
"message": "Invalid request fields",
"request_id": "request-uuid"
}
}| Status | Code | Action |
|---|---|---|
| 400 | invalid_request | Check fields, JSON, currency and idempotency key. |
| 401 | unauthorized | Check the secret, expiry and revocation status. |
| 403 | forbidden | Check scopes and workspace status; remove browser headers. |
| 404 | not_found | Check the endpoint and workspace ownership. |
| 405 | method_not_allowed | Use the documented HTTP method. |
| 409 | conflict | Check idempotency input, terminal state or workspace limits. |
| 413 / 415 | payload_too_large / unsupported_media_type | Send a small application/json request. |
| 429 | rate_limited | Wait at least the Retry-After value before retrying. |
| 500 | internal_error | Retry safely with the same idempotency key. |
Rate limits
The application permits 60 authenticated requests per minute per workspace, shared across its keys, and 120 API attempts per minute per source IP. A limited request returns 429 with Retry-After: 60. Cloudflare protections may also limit abusive traffic.
Retry without creating duplicates
- Persist a unique idempotency key with your test order before the first create request.
- On a timeout or a 5xx response, retry the identical payload with the same key.
- Use exponential backoff with jitter and a maximum retry count; honour Retry-After.
- Do not retry validation, permission or conflict errors without correcting the cause.
Do not poll continuously. Sandbox status changes only through simulation; retrieve the result when your test flow needs it. Webhook delivery is not implemented.