ABP Error Handling

Error response format

ABP returns errors in two shapes, depending on where the error originates:

Auth / rate-limit middleware errors use an error key:
{ "error": "Invalid or inactive API key" }
Application / route errors (validation, not-found, etc.) use the FastAPI-standard detail key:
{ "detail": "No odds found for given parameters" }

Handle both shapes in your client. Request-body validation errors (422) include field-level detail with a loc path:

{
  "detail": [
    {
      "loc": ["body", "orders", 0, "orderStake"],
      "msg": "Input should be greater than 0",
      "type": "greater_than"
    }
  ]
}

HTTP status codes

Status	Description
`200`	Success
`201`	Resource created
`204`	Resource deleted (no content)
`400`	Bad request — invalid or missing parameters
`401`	Unauthorized — invalid or inactive API key
`403`	Forbidden — missing API key header, or resource belongs to a different client
`404`	Not found — resource does not exist
`409`	Conflict — every order in the request is a duplicate (see below)
`422`	Validation error — request body failed validation
`429`	Rate limited — exceeded requests per second
`500`	Internal server error
`501`	Not implemented — futures markets (`futureId`) are not yet supported
`503`	Service unavailable — database or dependency down

Order decline reasons

When placing orders via POST /place-orders, orders that fail business validation are returned in the declinedOrders array (not as HTTP errors). Each declined order includes a declineReason:

Decline reason	Description
Stake exceeds limit	`orderStake` is higher than the available bookmaker limit
Stake below minimum	`orderStake` is below the bookmaker’s or account’s minimum
Invalid odds	`orderPrice` is not available or the market is suspended
No active accounts	No active bookmaker accounts available for this market
Currency conversion failed	Could not convert between order currency and bookmaker currency
Bookmaker not available	Specified bookmaker doesn’t have odds for this fixture/outcome
Odds temporarily unavailable	Odds could not be fetched in time; retry

Duplicate requestUuids are not returned as decline reasons. A duplicate is silently skipped; if every order in the request is a duplicate, the request returns 409 instead (see below).

Example declined order response:

{
  "status": "declined",
  "acceptedOrders": [],
  "declinedOrders": [
    {
      "requestUuid": "fb5f2dd9-c855-4ba9-8ef9-4c2278ca2f1d",
      "fixtureId": "id1000000861624412",
      "outcomeId": 161,
      "declineReason": "Order stake 15000.00 USD exceeds available limit 5000.00 USD",
      "bets": []
    }
  ]
}

Common errors

Authentication (401 / 403)

# Missing header → 403 {"detail": "Missing API key header: x-api-key"}
curl https://v2.55-tech.com/accounts

# Invalid or inactive key → 401 {"error": "Invalid or inactive API key"}
curl -H "x-api-key: wrong-key" https://v2.55-tech.com/accounts

Forbidden (403)

Returned when the API key header is missing, when the key is not allowed for the requested endpoint/sport/bookmaker, or when you attempt to access a resource that belongs to a different client.

{"detail": "Missing API key header: x-api-key"}
{"error": "Access denied to endpoint"}
{"detail": "Access denied: client not resolved"}

Duplicate request (409)

Returned only when every order in the request is a duplicate — each requestUuid was already processed or is in progress within the last 30 minutes. If only some orders are duplicates, those are skipped and the rest are processed normally.

{
  "detail": {
    "error": "All orders are duplicates",
    "duplicateUuids": ["eb45b192-317b-42d5-9f65-af497b9fa8c1"],
    "inProgressUuids": []
  }
}

Validation error (422)

Request body contains invalid data. Check the loc field for the problematic path:

{
  "detail": [
    {
      "loc": ["body", "orders", 0, "fixtureId"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Rate limiting (429)

Exceeded requests per second for your client. Default limit: 100/second (configurable per client).

{
  "detail": "Rate limit exceeded",
  "limit": "100",
  "retry_after": 1
}

The window resets every second — wait the retry_after interval before retrying.

Resilience patterns

ABP implements several resilience mechanisms that may affect your integration:

Circuit breakers

Per-bookmaker circuit breakers prevent cascading failures. If a bookmaker is experiencing issues, orders targeting that bookmaker may be declined until the circuit recovers. Opens after consecutive failures, automatically tests recovery, and resumes normal operation once the bookmaker responds successfully.

Emergency mode

In rare cases, the system may temporarily pause order processing during maintenance or upstream issues. The emergency WebSocket channel broadcasts status changes.

Order expiry

Orders have a default expiresAt of 5 seconds from creation (capped at 24 hours maximum). If a bet hasn’t been placed within this window, the order status changes to EXPIRED. Set a custom expiresAt for longer-lived orders.

Getting Started

Guides

Reference

Changelog

Error response format

HTTP status codes

Order decline reasons

Common errors

Authentication (401 / 403)

Forbidden (403)

Duplicate request (409)

Validation error (422)

Rate limiting (429)

Resilience patterns

Circuit breakers

Emergency mode

Order expiry

Next steps

Order Placement

WebSocket

​Error response format

​HTTP status codes

​Order decline reasons

​Common errors

​Authentication (401 / 403)

​Forbidden (403)

​Duplicate request (409)

​Validation error (422)

​Rate limiting (429)

​Resilience patterns

​Circuit breakers

​Emergency mode

​Order expiry

​Next steps

Order Placement

WebSocket

Error response format

HTTP status codes

Order decline reasons

Common errors

Authentication (401 / 403)

Forbidden (403)

Duplicate request (409)

Validation error (422)

Rate limiting (429)

Resilience patterns

Circuit breakers

Emergency mode

Order expiry

Next steps