API reference

Errors object

Copy as Markdown

# Errors object

## Inspect an error

`GET /v1/fixtures?limit=0`

Read the error object returned when a request fails.

Authentication: Bearer API key; authentication failures also use this object.

### Parameters

#### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| — | — | — | This response object accepts no parameters. |

#### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| — | — | — | This response object accepts no parameters. |

#### Body parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| — | — | — | This response object accepts no parameters. |

### Example request

```bash
curl 'https://api.opono.com/v1/fixtures?limit=0' \
  --header "Authorization: Bearer $OPONO_API_KEY"
```

### Response

| Field | Type | Description |
| --- | --- | --- |
| `error.type` | string | Broad error category. |
| `error.code` | string | Stable code listed below. |
| `error.message` | string | Explanation of the failure. |
| `error.cause` | string | Cause when present. |
| `error.fix` | string | Recovery instruction when present. |
| `error.param` | string or null | Invalid parameter, if known. |
| `error.doc_url` | string | Documentation link. |
| `error.request_id` | string or null | Request ID for support. |
| `error.retry.retryable` | boolean | Whether you can retry; may be absent during maintenance. |
| `error.retry.after_seconds` | number or null | Minimum retry delay in seconds. |
| `error.retry.strategy` | string | correct_request, backoff_with_jitter, or wait_for_change. |
| `error.retry.idempotency_key` | string | same, new, or not_applicable. |
| `error.credit_effect` | string | not_charged for confirmed failure; unknown if settlement is unconfirmed. |
| `error.recovery` | object or null | Recovery details, including fixture candidates when ambiguous. |
| `error.recovery.reason` | string | For lineup_invalid: xi_size, duplicate_player, bench_size, xi_bench_overlap, goalkeeper_count, formation_invalid, or formation_unsupported. |
| `error.recovery.unknown_id` | string | Player ID outside this side's squad when present. |
| `error.recovery.next_step` | string | Correction guidance, including the free squads URL when relevant. |
| `error.recovery.retry_at` | string | Account lockout expiry in ISO 8601 UTC when present; also honour Retry-After. |
| `error.rule / error.reason` | string | Rate-limit details when present. |
| `error.retryAfterMs` | number | Rate-limit retry delay in milliseconds when present. |

### Example response

400 response.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "'limit' must be a positive integer up to 200.",
    "cause": "The request does not satisfy the operation's input contract.",
    "fix": "Set limit to an integer from 1 to 200.",
    "param": "limit",
    "doc_url": "https://opono.com/docs#parameter_invalid",
    "request_id": "req_example",
    "retry": {
      "retryable": false,
      "after_seconds": null,
      "strategy": "correct_request",
      "idempotency_key": "not_applicable"
    },
    "credit_effect": "not_charged",
    "recovery": null
  }
}
```

### Errors

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `parameter_invalid` | A parameter has an invalid value. |
| 400 | `parameter_missing` | A required parameter is absent. |
| 401 | `invalid_api_key` | The credential cannot authenticate. |
| 401 | `key_revoked` | The API key has been revoked. |
| 401 | `key_expired` | The API key has expired. |
| 402 | `balance_too_low` | Your available balance cannot cover the request. |
| 403 | `scope_missing` | The key lacks the required scope. |
| 403 | `org_suspended` | Your account is suspended. |
| 403 | `ip_not_allowed` | The caller is outside the key's IP allowlist. |
| 403 | `tier_restricted` | The organisation plan does not include this operation. |
| 404 | `resource_missing` | The resource is missing or belongs to another account. |
| 409 | `idempotency_conflict` | An idempotency key conflicts with a prior request. |
| 429 | `rate_limited` | A request or authentication rate limit was exceeded. |
| 429 | `concurrency_limited` | The organisation has no available concurrent slot. |
| 429 | `loop_guard` | A repeated-call burst was refused. |
| 409 | `reservation_expired` | The simulation credit hold ended without delivery. |
| 503 | `fixture_lookup_incomplete` | The fixture lookup could not prove a unique match. |
| 404 | `fixture_not_found` | No matching simulation fixture exists. |
| 409 | `fixture_ambiguous` | The fixture lookup identifies multiple candidates. |
| 500 | `simulation_failed` | The simulation job failed. |
| 503 | `settlement_unknown` | Delivery settlement could not be confirmed. |
| 500 | `internal_error` | An unexpected internal failure occurred. |
| 503 | `dependency_unavailable` | Request admission is unavailable. |
| 500 | `payload_missing` | The result is unavailable or incomplete. |
| 502 | `provenance_missing` | The result is missing required source information. |
| 502 | `provenance_mismatch` | The result does not match the requested inputs. |
| 503 | `engine_cold_start` | The simulation service is starting. |
| 503 | `engine_overloaded` | The simulation service is at capacity. |
| 503 | `engine_unavailable` | The simulation service is unavailable. |
| 503 | `storage_unavailable` | The result is temporarily unavailable. |
| 400 | `fixture_not_covered` | The requested fixture is not available for simulation. |
| 503 | `refreshing` | The request can't be checked right now. |
| 503 | `capability_off` | This output is no longer available. |
| 503 | `capability_disabled` | This output is disabled. |
| 503 | `maintenance` | The API is paused for maintenance. |
| 400 | `lineup_invalid` | The custom XI, bench, goalkeeper selection, or formation is invalid; recovery.reason identifies the rule. |
| 400 | `player_not_in_squad` | A custom player ID is outside this side's squad; check recovery.unknown_id against the free squads list. |
| 409 | `lineups_not_announced` | Announced team sheets are unavailable; wait for publication or use auto. |
| 429 | `lineup_cooldown` | Custom-lineup requests are temporarily locked; wait for Retry-After and recovery.retry_at. |

Inspect an error

GET /v1/fixtures?limit=0

Read the error object returned when a request fails.

Authentication: Bearer API key; authentication failures also use this object.

Parameters

Path parameters

Name	Type	Required	Description
—	—	—	This response object accepts no parameters.

Query parameters

Name	Type	Required	Description
—	—	—	This response object accepts no parameters.

Body parameters

Name	Type	Required	Description
—	—	—	This response object accepts no parameters.

Example request

bash

curl 'https://api.opono.com/v1/fixtures?limit=0' \
  --header "Authorization: Bearer $OPONO_API_KEY"

Response

Field	Type	Description
`error.type`	string	Broad error category.
`error.code`	string	Stable code listed below.
`error.message`	string	Explanation of the failure.
`error.cause`	string	Cause when present.
`error.fix`	string	Recovery instruction when present.
`error.param`	string or null	Invalid parameter, if known.
`error.doc_url`	string	Documentation link.
`error.request_id`	string or null	Request ID for support.
`error.retry.retryable`	boolean	Whether you can retry; may be absent during maintenance.
`error.retry.after_seconds`	number or null	Minimum retry delay in seconds.
`error.retry.strategy`	string	correct_request, backoff_with_jitter, or wait_for_change.
`error.retry.idempotency_key`	string	same, new, or not_applicable.
`error.credit_effect`	string	not_charged for confirmed failure; unknown if settlement is unconfirmed.
`error.recovery`	object or null	Recovery details, including fixture candidates when ambiguous.
`error.recovery.reason`	string	For lineup_invalid: xi_size, duplicate_player, bench_size, xi_bench_overlap, goalkeeper_count, formation_invalid, or formation_unsupported.
`error.recovery.unknown_id`	string	Player ID outside this side's squad when present.
`error.recovery.next_step`	string	Correction guidance, including the free squads URL when relevant.
`error.recovery.retry_at`	string	Account lockout expiry in ISO 8601 UTC when present; also honour Retry-After.
`error.rule / error.reason`	string	Rate-limit details when present.
`error.retryAfterMs`	number	Rate-limit retry delay in milliseconds when present.

Example response

400 response.

json

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "'limit' must be a positive integer up to 200.",
    "cause": "The request does not satisfy the operation's input contract.",
    "fix": "Set limit to an integer from 1 to 200.",
    "param": "limit",
    "doc_url": "https://opono.com/docs#parameter_invalid",
    "request_id": "req_example",
    "retry": {
      "retryable": false,
      "after_seconds": null,
      "strategy": "correct_request",
      "idempotency_key": "not_applicable"
    },
    "credit_effect": "not_charged",
    "recovery": null
  }
}

Errors

Status	Code	Meaning
400	`parameter_invalid`	A parameter has an invalid value.
400	`parameter_missing`	A required parameter is absent.
401	`invalid_api_key`	The credential cannot authenticate.
401	`key_revoked`	The API key has been revoked.
401	`key_expired`	The API key has expired.
402	`balance_too_low`	Your available balance cannot cover the request.
403	`scope_missing`	The key lacks the required scope.
403	`org_suspended`	Your account is suspended.
403	`ip_not_allowed`	The caller is outside the key's IP allowlist.
403	`tier_restricted`	The organisation plan does not include this operation.
404	`resource_missing`	The resource is missing or belongs to another account.
409	`idempotency_conflict`	An idempotency key conflicts with a prior request.
429	`rate_limited`	A request or authentication rate limit was exceeded.
429	`concurrency_limited`	The organisation has no available concurrent slot.
429	`loop_guard`	A repeated-call burst was refused.
409	`reservation_expired`	The simulation credit hold ended without delivery.
503	`fixture_lookup_incomplete`	The fixture lookup could not prove a unique match.
404	`fixture_not_found`	No matching simulation fixture exists.
409	`fixture_ambiguous`	The fixture lookup identifies multiple candidates.
500	`simulation_failed`	The simulation job failed.
503	`settlement_unknown`	Delivery settlement could not be confirmed.
500	`internal_error`	An unexpected internal failure occurred.
503	`dependency_unavailable`	Request admission is unavailable.
500	`payload_missing`	The result is unavailable or incomplete.
502	`provenance_missing`	The result is missing required source information.
502	`provenance_mismatch`	The result does not match the requested inputs.
503	`engine_cold_start`	The simulation service is starting.
503	`engine_overloaded`	The simulation service is at capacity.
503	`engine_unavailable`	The simulation service is unavailable.
503	`storage_unavailable`	The result is temporarily unavailable.
400	`fixture_not_covered`	The requested fixture is not available for simulation.
503	`refreshing`	The request can't be checked right now.
503	`capability_off`	This output is no longer available.
503	`capability_disabled`	This output is disabled.
503	`maintenance`	The API is paused for maintenance.
400	`lineup_invalid`	The custom XI, bench, goalkeeper selection, or formation is invalid; recovery.reason identifies the rule.
400	`player_not_in_squad`	A custom player ID is outside this side's squad; check recovery.unknown_id against the free squads list.
409	`lineups_not_announced`	Announced team sheets are unavailable; wait for publication or use auto.
429	`lineup_cooldown`	Custom-lineup requests are temporarily locked; wait for Retry-After and recovery.retry_at.