Errors

Every error the Fibric API returns uses standard HTTP status codes and one consistent JSON envelope. The code is stable and machine-readable; branch on it, never on message, which is human-readable and may change. This page is the complete code table, grouped by status, with the conflict semantics that matter most: idempotency replay and the single-flight lock.

#The error envelope

{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "Plan pl_7c1a is already executed and cannot be approved.",
    "doc_url": "https://fibric.io/docs/errors#state_conflict",
    "request_id": "req_9b3e21f0"
  }
}

The envelope is the whole contract: no error returns a bare string, an HTML page, or a different JSON shape, including 429 and 5xx responses. A client that handles the envelope handles every failure the API can produce.

#Retryability at a glance

Before the full table, the decision that matters most in a client: given a status, is an unchanged retry ever correct?

#Codes by HTTP status

Type invalid_request_error. The request never reached business logic. Do not retry unchanged.

Type authentication_error. The server does not know who you are. Do not retry with the same credentials.

Type permission_error. The server knows who you are and the answer is no.

Type not_found_error.

Type conflict_error. The request was well formed but collided with the current state. The two conflict codes with dedicated semantics, idempotency_conflict and entity_locked, are detailed below the table.

Type validation_error. The request was understood and refused on its merits, usually by governance.

Type rate_limit_error. Budgets, windows, and quota mechanics are documented in Rate limits & quotas.

Type api_error. Something failed on our side or upstream of us. Retries are safe on any request that carried an Idempotency-Key and on all reads.

#Idempotency conflict semantics

An Idempotency-Key binds a key to the exact request body it was first seen with. Three outcomes are possible on replay, and only one is an error:

Keys are scoped per tenant and route, and retained for 24 hours. Derive keys from the operation's natural identity, for example magento:SO-10884:v7 for an event or approve-pl_7c1a for an approval, rather than from random values, so a crashed-and-restarted worker replays instead of duplicating. Side-effecting plan actions additionally carry their own idempotency_key in the body, enforced by the executor itself; a replayed action disposes as DEDUP and is receipted, not errored. See Single-flight & idempotency.

#Single-flight 409 semantics

The executor serializes side effects per entity_key: one thing in flight per order, per room, per asset. Inside a single plan this is invisible, actions on the same entity simply run in order. Across requests, it surfaces as a lock:

HTTP/1.1 409 Conflict
Retry-After: 4

{
  "error": {
    "type": "conflict_error",
    "code": "entity_locked",
    "message": "order:SO-10884 is locked by plan pl_7c1a; retry after the in-flight work disposes.",
    "doc_url": "https://fibric.io/docs/errors#entity_locked",
    "request_id": "req_4d17ab02"
  }
}

Handling rules:

• The lock is per entity, not per tenant. Work on other entities proceeds normally while one entity is locked.
• Retry the same request unchanged, with the same Idempotency-Key, after Retry-After seconds. If the in-flight work already did what your request would do, the idempotency layer dedupes and you get the stored result rather than a second side effect.
• Do not treat entity_locked as failure in monitoring. It is the kernel refusing to interleave two writes on one entity, which is the behavior that prevents a double hold or a double refund.

#Working with request ids

Every response, success or failure, carries the request id, in the body for errors and in the X-Request-Id response header for everything. The same id appears in any receipt the request produced, so one identifier joins your client logs, our server logs, and the audit ledger.

# capture the request id from the error body
curl -s -X POST https://api.fibric.io/v1/plans/pl_7c1a/approve \
  -H "Authorization: Bearer sk_live_3f9c2a7b8e1d4f60a2c9" \
  -H "Content-Type: application/json" \
  -d '{"approver": "l.ops@example.com"}' | jq -r '.error.request_id'
# req_9b3e21f0

# then find any receipt the request wrote
curl -s "https://api.fibric.io/v1/receipts?request_id=req_9b3e21f0" \
  -H "Authorization: Bearer sk_live_3f9c2a7b8e1d4f60a2c9"

Log the request id on every non-2xx response as a matter of course. When you contact support, it is the one field that lets us find the exact request without guessing from timestamps.