Errors & Retries

Every error response uses a single uniform envelope.

Error envelope

{
  "error": {
    "code": "bad_request",
    "message": "human-readable summary",
    "param": "address",
    "doc_url": "https://docs.piratecrew.fun/docs/error-codes-reference#bad_request"
  },
  "meta": {
    "request_id": "req_01HXYZ…"
  }
}

error.code — stable identifier for routing logic (see list below).
error.message — human-readable summary.
error.param (optional) — the offending field on 400 bad_request.
error.doc_url (optional) — deep-link into the docs.
meta.request_id — opaque ID; give this to support when reporting an issue.

Error codes

code is a stable identifier suitable for routing logic — for example:

bad_request
unauthorized
forbidden
not_found
conflict
rate_limited
internal_error

Status codes

Code	Meaning	Retry?
400	Validation failure — required field missing, regex mismatch, recent-ticker cooldown, malformed pubkey	No — fix the payload
401	Authorization header missing or malformed	No
403	API key invalid, revoked, or missing a required scope	No — contact admin / request scope
404	Resource not found (account, pool, proof, etc.)	No
409	`Idempotency-Key` reused with a different request body	No — use a fresh key for a different request
429	Per-minute or per-day quota exceeded	Yes — exponential backoff from 1s
500	Unhandled server error	Yes — max 3 attempts with jitter

Common 400 cases

See Common Validation Errors.

Common 403 cases

Missing scope — error.message: "API key missing required scope(s): fees:claim". Either request the scope on your key, or call the endpoint in mode=unsigned.

409 — idempotency conflict

You sent the same Idempotency-Key with a different request body. Either:

Use a fresh v4 UUID, or
Resend with the exact same body to get the cached response.

See Idempotency.

500 hygiene

500 responses include the underlying error message only when NODE_ENV=development. In production you'll see "Something went wrong" — check the service logs for the full stack.

Recommended client retry policy

See Retry Policy.