Errors & Request IDs

Every error from the Public API returns a single, predictable JSON envelope. Build your error handling against error_code, not against parsing detail strings — messages are human-readable and may change, codes do not.

Error envelope

{
  "error_code": "VALIDATION_ERROR",
  "detail": "Validation error",
  "details": [
    {
      "field": "quantity",
      "message": "Input should be greater than 0",
      "type": "greater_than"
    }
  ],
  "request_id": "b2f7c1e0-9a4d-4a5e-8f3a-1c2b3d4e5f60"
}

Field	Meaning
`error_code`	Stable machine-readable code — key your retry/alert logic on this
`detail`	Human-readable summary
`details`	Present on validation errors: an array of `{field, message, type}`
`request_id`	Echo of your `X-Request-ID` header, or `null` if you did not send one

Status → error_code mapping

HTTP status	error_code	Typical cause
400	`BAD_REQUEST`	Malformed request semantics (e.g. missing idempotency key, non-metered item)
401	`UNAUTHORIZED`	Missing, malformed, or expired API key
403	`FORBIDDEN`	Key valid but not permitted for this resource
404	`NOT_FOUND`	Resource does not exist in your organization
405	`METHOD_NOT_ALLOWED`	Wrong HTTP verb on an existing path
409	`CONFLICT`	State conflict (e.g. duplicate active resource)
422	`VALIDATION_ERROR`	Body/query fails schema validation — see `details`
429	`RATE_LIMITED`	Too many requests (includes `Retry-After` header)
500	`INTERNAL_SERVER_ERROR`	Unexpected server failure — safe to retry with backoff
503	`SERVICE_UNAVAILABLE`	Temporary unavailability — retry with backoff

Request IDs for tracing

Send an X-Request-ID header with any request and Floatless echoes it back in the error envelope's request_id — and in logs, so support can find the exact request:

curl https://api.floatless.com/api/public/v1/invoices \
  -H "Authorization: Bearer sk_live_..." \
  -H "X-Request-ID: checkout-batch-2026-09-06-041"

Use one unique request ID per logical operation attempt (generate a new one when you retry) and include it in your own logs — it is the fastest path from your error monitor to a Floatless support investigation.

Retry guidance by class

Class	Codes	Client behavior
Your bug	400, 405, 422	Do not retry; fix the request. 422 `details` names the field.
Auth	401, 403	Do not retry with the same key; rotate or fix credentials.
Not found	404	Refresh your local copy of the resource; do not blind-retry.
Conflict	409	Re-read state, reconcile, then decide.
Transient	429, 500, 503	Retry with exponential backoff; honor `Retry-After` on 429.

Next steps

PreviousMCP server NextPagination