Guides

Errors

Copy as Markdown

# Errors

Read error.code, error.fix, and error.retry before you retry a failed request.

## Fix the request

| Status | Action |
| --- | --- |
| 400 | Correct the named parameter or invalid lineup. |
| 401 | Check or replace your API key. |
| 402 | Check your credit balance and plan. |
| 403 | Check permissions and account access. |
| 404 | Use a returned ID before kick-off. |
| 409 | Resolve fixture ambiguity, idempotency conflict, or wait for announced lineups. |

For fixture_ambiguous, choose an ID from error.recovery.candidates.

## Retry safely

1. For 429 or retryable 503, wait for Retry-After and error.retry.after_seconds.
2. Use exponential backoff with jitter.
3. Keep the same Idempotency-Key and exact body unless error.retry.idempotency_key is new.
4. For refreshing, wait for the delay and submit again with a new key.
5. For wait_for_change, wait for the stated condition before submitting again.

## Check charging

Confirmed failed attempts have credit_effect not_charged; they do not refund an earlier delivery.

For lineup_invalid or player_not_in_squad, correct your selection using [Squads](/docs/reference/squads). For lineup_cooldown, wait until recovery.retry_at; see [Choosing lineups](/docs/choosing-lineups).

For settlement_unknown, a charge may have committed, so retry with the original Idempotency-Key or poll the same job.

If you have neither, contact [Support](/docs/support) with request_id before resubmitting.

See the [Errors object](/docs/reference/errors) for every field and code.

Read error.code, error.fix, and error.retry before you retry a failed request.

Fix the request

Status	Action
400	Correct the named parameter or invalid lineup.
401	Check or replace your API key.
402	Check your credit balance and plan.
403	Check permissions and account access.
404	Use a returned ID before kick-off.
409	Resolve fixture ambiguity, idempotency conflict, or wait for announced lineups.

For fixture_ambiguous, choose an ID from error.recovery.candidates.

Retry safely

For 429 or retryable 503, wait for Retry-After and error.retry.after_seconds.
Use exponential backoff with jitter.
Keep the same Idempotency-Key and exact body unless error.retry.idempotency_key is new.
For refreshing, wait for the delay and submit again with a new key.
For wait_for_change, wait for the stated condition before submitting again.

Check charging

Confirmed failed attempts have credit_effect not_charged; they do not refund an earlier delivery.

For lineup_invalid or player_not_in_squad, correct your selection using Squads. For lineup_cooldown, wait until recovery.retry_at; see Choosing lineups.

For settlement_unknown, a charge may have committed, so retry with the original Idempotency-Key or poll the same job.

If you have neither, contact Support with request_id before resubmitting.

See the Errors object for every field and code.

Error codes