Errors, limits, and configuration reference

This is the reference page you'll keep open in the other tab — error shapes, status codes, validation rules, and the deployment-level limits that shape what your integration can do.

For per-endpoint failure modes, see the topic docs (User Onboarding (users, KYC, terms), Market Orders (single-contract trades), Parlays (2–12 leg trades), Wallets, Webhooks (push events)).

1. Error response shapes

`ErrorResponse` — single business error

Returned for most 4xx and 5xx errors.

{ "error": "user already exists", "code": "user_already_exists" }

`ValidationErrorResponse` — per-field validation

Returned for 422 on body validation.

{
  "errors": [
    { "field": "firstName",   "message": "required" },
    { "field": "dateOfBirth", "message": "must be age 19-125" }
  ]
}

`StaleTermsResponse` — only on `POST /users/USERID/terms` 409

{ "error": "terms version stale", "code": "stale_terms", "currentTotalVersion": 8 }

Use currentTotalVersion to re-prompt the user with the right version. See User Onboarding (users, KYC, terms).

2. HTTP status codes

HTTP	Meaning	Common triggers
`200`	OK	Read, or idempotent write that already happened
`201`	Created	`POST /users`, `POST /parlays`, `POST /push/register`
`202`	Accepted (async)	`POST /market-orders` — poll `refId`
`204`	No Content	`DELETE`, `POST /users/USERID/terms` first-time acceptance
`400`	Bad Request	Malformed JSON, bad query params
`401`	Unauthorized	JWT missing/invalid, `sub` ≠ `USERID`
`402`	Payment Required	Insufficient balance (parlays)
`404`	Not Found	Bad UUID, INDIVIDUAL ISV reading `/wallets` without `sub`
`409`	Conflict	Duplicate user, stale terms version, push already registered, non-zero balance on delete
`422`	Unprocessable	Field validation, KYC pending, insufficient liquidity, immutable field touched
`500`	Internal Server Error	Unhandled backend failure

3. Common error codes

`code`	HTTP	Triggered by
`user_already_exists`	409	`POST /users` — identity hash (name + DOB + SSN) collides
`user_not_found`	404	Any user-scoped path with an unknown UUID
`user_pending_kyc`	409/422	`GET /users/USERID` before the user is verified (409), or trying to trade before KYC has resolved (422)
`non_zero_balance`	409	`DELETE /users/USERID` while balance > 0 (INDIVIDUAL ISVs)
`stale_terms`	409	`POST /users/USERID/terms` with an out-of-date `totalVersion`
`INVALID_CONTRACT`	400/422	Unknown or stale `contractId` on order endpoints
`internal_server_error`	500	Unhandled backend failure

4. Request validation rules

`CreateUserRequest`

Field	Rule
`firstName`, `lastName`	Required, non-empty. Immutable.
`dateOfBirth`	Required. `YYYY-MM-DD`. Age 19–125. Immutable.
`ssnLastDigits`	Required. Exactly 4 numeric digits. Immutable.
`addressLine1`, `city`	Required.
`state`	Required. 2-letter USPS code.
`zip`	Required. 5–10 chars.
`countryCode`	Required. ISO 3166 alpha-2.
`phoneNumber`	Optional. If given, 10 numeric digits, unformatted.
`email`	Optional. If given, valid email format.
`emailVerifiedAt`	Required. UTC timestamp.
`phoneVerifiedAt`	Optional. UTC timestamp.

`UpdateUserRequest`

Same field-level rules as above, but all fields are optional, and firstName / lastName / dateOfBirth / ssnLastDigits must not appear. Including any of them returns 422.

`EstimateMarketOrderRequest`

Field	Rule
`contractId`	Required.
`quantity`	Required. `>= 0` (use `0` to peek the best price).

`SubmitMarketOrderRequest`

Field	Rule
`contractId`	Required.
`quantity`	Required. `> 0` (strict).

`CreateParlayRequest`

Field	Rule
`legs`	Required. 2–12 items.
`legs[].eventId`, `marketId`, `outcomeId`	Required. `> 0`.
`legs[].contractId`	Required.
`legs[].strike`	Optional (spreads/totals).
`quantity`	Required. `> 0`.

`ConfirmParlayRequest`

Field	Rule
`quantity`	Required. `> 0`. Must not exceed `offer.maxQuantity` from the quote.

`AcceptTermsRequest`

Field	Rule
`totalVersion`	Required. `> 0`.

`GET /wallets/transactions` query

Field	Rule
`limit`	Optional. Integer in `1..200`. Defaults to `50`.
`before`	Optional. Integer. Pass `nextCursor` from a previous response.

5. Auth-level constraints

Constraint	Value
JWT max `exp - iat`	< 300 seconds
JWT `nbf`/`iat` clock skew	±30 seconds
`sub` ↔ `USERID` match on user routes	Required
`digest` claim	Base64URL(SHA256(body)), no padding
`subsig` claim	Base64URL(HMAC-SHA256(secret, "_{::")), no padding}

See Authentication.

6. Webhook delivery limits

Setting	Default	Effect
Delivery timeout	5 s	Your receiver must respond `2xx` within this window.
Error threshold	3 consecutive failures	Receiver gets paused; resumes when `GET /health` returns 200.
Retry delay	10 s	Time between retries.
Message max age	24 h	Older messages are dropped, not delivered.

See Webhooks (push events).

7. Quick lookup: "what does this status code usually mean?"

A field guide for log triage.

You see...	First look at...
`401` on every call	JWT generation — check `alg=EdDSA`, `kid==iss`, `aud="prophetx"`, clock skew, base64 padding
`401` on `USERID` routes only	`sub` claim ≠ `USERID`; or missing `subsig`
`402` on parlay confirm	User balance vs. fee + quantity
`404` on `/wallets` with no `sub`	You're INDIVIDUAL, there's no pot — call with `sub` for the user wallet
`409 user_already_exists`	Same person, different account — identity hash collision
`409 stale_terms`	Re-fetch `/terms`, show the new version, re-prompt
`409 non_zero_balance`	Settle, refund, or withdraw before deleting (INDIVIDUAL)
`422 INVALID_CONTRACT`	Stale `contractId` — re-fetch markets
`422 user_pending_kyc`	Wait for `GET /kyc-status` to read `SUCCESS`
Parlay `failReason: "price moved"`	Re-quote with the same legs

Errors, limits, and configuration reference

1. Error response shapes

ErrorResponse — single business error

ValidationErrorResponse — per-field validation

StaleTermsResponse — only on POST /users/USERID/terms 409

2. HTTP status codes

3. Common error codes

4. Request validation rules

CreateUserRequest

UpdateUserRequest

EstimateMarketOrderRequest

SubmitMarketOrderRequest

CreateParlayRequest

ConfirmParlayRequest

AcceptTermsRequest

GET /wallets/transactions query