Errors, pagination, and idempotency

Structured errors

Errors use a stable machine-readable code plus a human-readable message. Treat the HTTP status and code as the contract; messages may become more specific.

Status	Meaning	Client action
400	Invalid operation or state transition	Correct the request
401	Missing or invalid authentication	Refresh or replace the credential
403	Authenticated but not permitted	Check role and tenant policy
404	Resource is absent or outside the tenant	Do not infer cross-tenant existence
409	Idempotency conflict or concurrent state change	Reconcile before retrying
422	Payload validation failed	Correct the named fields
429	Rate limit reached	Back off and retry
5xx	Transient service failure	Retry with bounded exponential backoff

Every response includes X-Request-ID. Log it with your internal operation ID and provide it when contacting support.

Cursor pagination

List operations return a bounded page and a next_cursor when more records exist. Pass that opaque value back unchanged:

curl "https://api.fideralabs.com/v1/alerts?state=new&limit=50" \
  --header "Authorization: Bearer $FIDERA_API_KEY"

curl "https://api.fideralabs.com/v1/alerts?state=new&limit=50&cursor=$NEXT_CURSOR" \
  --header "Authorization: Bearer $FIDERA_API_KEY"

Do not parse, sort, derive, or persist assumptions about cursor structure. Keep all filters stable while walking a result set.

Idempotent creation

Send an Idempotency-Key for operations that can create work or provider spend. Scope the value to the business action, not a single network attempt.

Idempotency-Key: payment-9842-screen-v1

Replaying the same key and body returns the original resource. Reusing the key with a different body returns 409. Persist the key beside your business record so workers and retries converge on the same Check.

Retry policy

Retry connection failures, 429, and selected 5xx responses with jittered exponential backoff. Do not blindly retry validation errors or state transitions. A safe default is four attempts capped at 30 seconds, followed by queueing for operator reconciliation.