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
ErrorResponse — single business errorReturned for most 4xx and 5xx errors.
{ "error": "user already exists", "code": "user_already_exists" }ValidationErrorResponse — per-field validation
ValidationErrorResponse — per-field validationReturned 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
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 on POST /parlays/{id}/confirm. Not used by POST /market-orders — that endpoint accepts the order with 200 status=pending and lets the matching engine cancel it. See Market Orders. |
403 | Forbidden | IP geo-gate denial (GEO_BLOCKED) or a required permission not granted for the user (x-required-permission on the endpoint). Surface as ForbiddenError. |
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), DELETE /users/USERID on any user who hasn't reached SUCCESS (409 — the code says "pending" but the check is "not verified", so FAILURE / MORTALITY / PEP / OFAC users hit this too), 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 |
kyc_not_retryable | 409 | POST /users/USERID/kyc-retry when the user isn't in FAILURE status or when the per-ISV retry limit has been exhausted. Check GET /kyc-status to tell them apart — a FAILURE user that still returns this code means retries are exhausted. See User Onboarding. |
address_not_found | 422 | POST /validate-address — Smarty could not find a match for the submitted US address. Ask the user to correct and re-validate before you try to create the user. |
limit_exceeded | 4xx | Surfaces on the embedded UI's AeroPay or PayNearMe deposit/withdraw calls when the requested amount would exceed a configured per-user cap (daily, pending, or per_tx). Body includes kind (which cap), limit, and remaining. Not called from the ISV backend — the embedded UI reads limits and enforces this itself. See Embedded UI. |
INVALID_CONTRACT | 400/422 | Unknown or stale contractId on order endpoints |
GEO_BLOCKED | 403 | The client_ip claim is missing or not a valid IP, or resolves to an OFAC-sanctioned country or an unsupported US state (currently Nevada and Utah). All other locations are allowed — this is not a US-only check. Only user-scoped requests (with sub) are geo-checked. Surface to the user as a region notice, not an auth error. See Authentication. |
permission_denied | 403 | The user lacks a permission required by the endpoint (x-required-permission on the spec). Inspect GET /users/USERID/permissions to see which permissions are granted and any denyReason. The response body may include pending_gates: ["<gate>", …] — the specific gates blocking the permission. A pending_gates: ["not-suspended"] value specifically means the user is currently suspended (see User Onboarding). |
internal_server_error | 500 | Unhandled backend failure |
4. Request validation rules
CreateUserRequest
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
UpdateUserRequestSame 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
EstimateMarketOrderRequest| Field | Rule |
|---|---|
contractId | Required. |
quantity | Required. >= 0 (use 0 to peek the best price). |
SubmitMarketOrderRequest
SubmitMarketOrderRequest| Field | Rule |
|---|---|
contractId | Required. |
quantity | Required. > 0 (strict). |
expectedAveragePrice | Required. Integer (American price). Echo back from the /estimate response. |
priceList | Required. Non-empty list[int]. Echo back from the /estimate response — at least one level required. The backend rejects the submit if the live price has moved off these levels. |
CreateParlayRequest
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
ConfirmParlayRequest| Field | Rule |
|---|---|
quantity | Required. > 0. Must not exceed offer.maxQuantity from the quote. |
AcceptTermsRequest
AcceptTermsRequest| Field | Rule |
|---|---|
totalVersion | Required. > 0. |
GET /transactions query
GET /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, ": |
client_ip claim | Required on user-scoped routes when geofencing is enabled. Plain IPv4/IPv6 string of the end user's IP, not your server's. Missing or unparseable → 403 GEO_BLOCKED. OFAC-sanctioned country or unsupported US state (currently Nevada and Utah) → 403 GEO_BLOCKED. Other locations are allowed. Not checked on ISV-only routes. |
| Inbound webhook signing | EdDSA (Ed25519). Verify with the ProphetX public key. |
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. |
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 |
403 GEO_BLOCKED | The client_ip claim is missing, invalid, or resolves to an OFAC-sanctioned country or an unsupported US state (currently Nevada and Utah). Confirm you're forwarding the trader's IP, not your server's. |
403 permission_denied | User lacks an x-required-permission for the endpoint. Call GET /users/USERID/permissions to see which permissions/gates are granted. |
402 on parlay confirm | User balance vs. fee + quantity |
Market order came back status: "canceled" with filledQuantity: 0 seconds after submit | Insufficient balance or the order simply never matched — market-orders don't 402 on submit, and canceled/unfilled doesn't currently distinguish the two causes. Poll get() and check status. |
404 on /wallets with no sub | You're INDIVIDUAL, there's no standing fund — 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 |
422 on POST /market-orders after a clean estimate | Live price moved off priceList — re-call /estimate and resubmit with the new expectedAveragePrice + priceList |
Parlay failReason: "price moved" | Re-quote with the same legs |
8. Fee configuration
Fees aren't a single, fixed formula for your ISV. ProphetX can configure a fee curve scoped to your ISV account as a whole, or more specifically to a tournament, an event, or a product/market type (sub_type — e.g. moneyline vs parlay) — all independently and in combination. If you're seeing different effective fees across different bet types or events for the same ISV, that's expected behavior from more specific configuration taking precedence, not inconsistent pricing.
Market orders and parlays are priced off separate fee models internally (distinct formulas, not a shared one), even though both resolve through the same underlying fee engine. Don't assume a fee change on one order type carries over to the other.
There is currently no self-serve way to view your own fee schedule or volume — this is communicated by your ProphetX contact, not through the API. If you need your current configuration or usage figures, ask your contact directly rather than looking for an endpoint.
Updated 5 days ago
