Errors

CryptoComply uses standard HTTP status codes and returns a JSON body describing what went wrong. This page covers the two body shapes and what each status code means.

The OpenAPI schema does not formally model error bodies; the shapes below are what the API emits today.

Error body shapes

Validation errors (400) are keyed by field. Errors that aren't tied to a single field appear under non_field_errors:

{
  "blockchain": ["This field is required."],
  "non_field_errors": ["Address already registered in this organization."]
}

Other errors (authentication, permission, not-found, conflict) return a single detail message:

{ "detail": "Authentication credentials were not provided." }

When you parse error responses, handle both shapes: a field-keyed object on 400, and a detail string otherwise.

Status codes

Code	Meaning	What to do
200 / 201 / 204	Success (read / created / deleted with no body)	Continue.
400 Bad Request	Invalid input	Read the field-keyed body and fix the request. Don't retry unchanged.
401 Unauthorized	Missing or invalid credentials	Check the Authorization: Api-Key <key> header, including the Api-Key prefix.
403 Forbidden	Authenticated but not allowed	The key is read-only, or the member's role lacks the permission. Use a full-access key or adjust the role.
404 Not Found	Object doesn't exist, or belongs to another organization	Confirm the org_pk and object id. Cross-tenant access returns 404.
409 Conflict	The request conflicts with current state	A competing edit, or a write that needs confirmation. Re-fetch the object and retry with current state.
429 Too Many Requests	A rate-limited endpoint was called too often	Honor the Retry-After header and back off before retrying.
500 and up	Server-side error	Retry idempotent reads with backoff (below). If it persists, contact support.

Retries and backoff

• Reads (GET) are safe to retry. On a 5xx or a network error, retry with exponential backoff — for example 1s, 2s, 4s — with jitter, and cap the attempts.
• Be careful retrying writes. A POST that times out may have succeeded. Before retrying a create, re-query to check whether the object already exists.
• Don't retry 4xx. A 400, 401, 403, or 404 will fail again unchanged — fix the request instead.

Rate limits and webhooks

Some endpoints are rate-limited and return 429 with a Retry-After header when you exceed the limit; honor it. There are no per-request quota headers and no webhooks yet. Build polling loops to be considerate — page efficiently and avoid tight retry loops — and this page will be updated if those features ship.

What's next

• Authentication & API keys — resolving 401 and 403.
• Pagination — handling failures mid-page.