Errors

Error codes, formats, and handling guidance.

Error Format

All API errors return a consistent JSON structure:

{
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Entity with the given ID does not exist.",
    "details": {}
  }
}

HTTP Status Codes

Status	Meaning	Action
`400`	Bad Request	Fix request body, parameters, or query strings
`401`	Unauthorized	Include a valid API key in the Authorization header
`403`	Forbidden	Key lacks required scope, IP not allowed, or key revoked
`404`	Not Found	Resource does not exist
`409`	Conflict	Duplicate entity, wallet already registered, etc.
`422`	Unprocessable Entity	Validation error — check the details object
`429`	Too Many Requests	Back off and retry after the X-RateLimit-Reset time
`500`	Internal Server Error	Retry with exponential backoff; contact support if persistent
`503`	Service Unavailable	Temporary outage — retry shortly

Common Error Codes

Code	Description
`ENTITY_NOT_FOUND`	Entity ID does not exist
`WALLET_NOT_REGISTERED`	Wallet address is not registered for any entity
`COMPLIANCE_CHECK_FAILED`	One or more compliance checks did not pass
`ENTITY_SUSPENDED`	Entity is suspended and cannot transact
`WALLET_FROZEN`	Wallet compliance has been revoked on the oracle
`SANCTIONED_ADDRESS`	Address appears on a sanctions list
`TRAVEL_RULE_REQUIRED`	Transfer exceeds threshold and requires travel rule data
`DUPLICATE_ENTITY`	Entity with same legal name and jurisdiction exists
`INVALID_CHAIN_ID`	Chain ID is not supported
`RATE_LIMIT_EXCEEDED`	API key has exceeded its rate limit tier

Handling Errors

Python

import httpx

resp = httpx.post("https://api.overvoid.io/v1/onboarding/entities", ...)

if resp.status_code == 429:
    # Rate limited — check headers
    reset_at = int(resp.headers["X-RateLimit-Reset"])
    # Wait until reset_at (Unix timestamp)
elif resp.status_code >= 400:
    error = resp.json()["error"]
    print(f"Error {error['code']}: {error['message']}")
    if error.get("details"):
        print(f"Details: {error['details']}")

Retry Strategy

For transient errors (5xx, timeouts), use exponential backoff:

1st retry: 1 second
2nd retry: 2 seconds
3rd retry: 4 seconds
Max 5 retries with jitter

Do not retry 4xx errors (except 429) — they indicate a client-side issue that must be fixed.