Errors & troubleshooting
Errors use a problem-details JSON body with a stable machine-readable code and a human detail:
Code
Switch on the uppercase code value in code; show detail to humans. Validation, auth, and
rate-limit failures are recorded but never charge credits.
Status codes
| Status | Meaning |
|---|---|
400 | Malformed request |
401 | Missing or invalid key |
403 | Inactive account, wrong environment, revoked key, or missing scope |
409 | Duplicate x-request-id for the same account and environment |
413 | Request payload exceeds the endpoint limit |
422 | Insufficient credits or unsupported calculation scenario |
429 | Rate limit or credit limit exceeded |
503 | Calculation service unavailable |
5xx | Server error — safe to retry with backoff |
All public API errors are returned as application/problem+json. The stable required fields are
type, title, status, detail, instance, code, and message; responses can also include
correlationId, retryAfterMs, and stage.
Troubleshooting
- 401 / 403 — check you're sending the right credential for the plane. Calculation calls need a
product key (
pw_test_/pw_live_), not a management token (pw_mgmt_…); a live key won't work against test data and vice versa. See Authentication & API keys. - 422 — the scenario is invalid (e.g. a duplicated card, an impossible board, or a payout total
that doesn't add up). The
detailsays which field. - 422 — top up your credit wallet, or you've hit a test-mode limit.
- 429 — you're rate limited; back off and retry. See Rate limits.
Request IDs
Every successful calculation response includes a request ID in the JSON body as requestId.
Log it. Quote it in support requests so we can trace the exact call. On requests, x-request-id is
the optional idempotency key; reusing a completed value for the same account and environment returns
409 and is not billed again.
Retries & idempotency
Calculation calls accept x-request-id as an idempotency key. Reusing a completed request ID for
the same developer API account and environment returns 409 and is not billed again.
x-correlation-id is for tracing only and is ignored for idempotency.
Retry 429 and 5xx with exponential backoff and jitter. If the problem body includes
retryAfterMs, wait at least that long before retrying. Do not retry 400, 401, 403, or 422
without changing the request, key, account state, or credit balance. The management API does not
currently publish an idempotency-key contract for mutating calls.
Getting help
When you contact support, include your account ID and a request ID so we can find the call quickly.