Error taxonomy

All error responses from /api/public/v1/* use a single envelope:

{ "ok": false, "error": "<short code>", "detail": "<optional long detail>" }

• ok is always false on non-2xx responses.
• error is a short, stable, human-readable code suitable for logging and for switch statements. Treat it as a string, not a strict enum — new values may be introduced over time.
• detail is optional extra context. When present it repeats error or augments it.

Unhandled 500 responses additionally carry a request_id field. Include it in any support request.

Inspection order

When parsing an error envelope, inspect:

1. error (the short stable code)
2. detail (extra context)
3. message (legacy alias for detail)

Stop at the first non-empty field.

Full catalog

HTTP	error	Recommended client action
400	violation_id must be {blueprint_id}:{policy_code}	Build the path as {scenario_id}:{policy_code}. Do not retry.
400	Malformed token	The result_token is invalid. Re-submit via POST /evaluate.
400	Organization context required	Keys admin endpoints only. Ensure the session has a selected organization.
400	Key already revoked	Refresh the key list; do not retry revoke.
400	Key cannot be rotated (inactive or revoked)	Create a new key.
400	scenario_ids must contain 1 to 100 items	Provide between 1 and 10 IDs (legacy message; public cap is 10).
401	Missing or invalid Authorization header	Attach Authorization: Bearer fb_live_....
401	Invalid API key format	Key must start with fb_live_.
401	Invalid or expired API key	Key revoked, expired, or unknown. Rotate or recreate.
401	API key context missing	Internal; should not occur in practice. Retry once; otherwise report.
401	Session authentication required	Keys admin endpoints. Sign in again.
401	Invalid, expired, or already-used result token	Do not retry; fetch results via GET /evaluations/{id} instead.
403	Browser access not allowed	Do not call from a browser; this API is server-to-server only.
403	IP address not allowed	Call from an IP in the key's allowlist.
403	Missing request signature	Attach the X-FB-Signature header. See Authentication.
403	Invalid request signature	Verify HMAC computation. See Sign requests with HMAC.
403	org_id does not match API key organization	The org_id in the body or path must equal the key's org.
403	Not authorized for this evaluation	Evaluation belongs to another org. Do not retry.
403	Key lacks governance:evaluate permission	Recreate the key with governance:evaluate permission.
403	Not authorized	Keys admin endpoints. The key belongs to a different org.
404	Scenario not found	Import the scenario into the organization first.
404	Blueprint not found	Same as above.
404	Evaluation not found	Unknown or purged evaluation ID.
404	Key not found	Refresh the key list.
413	Request body too large	Reduce payload size below 10 MB.
429	Rate limit exceeded	Honor Retry-After. See Rate limits and retries.
500	Remediation generation failed	Transient. Retry with exponential backoff up to 3 times.
500	Internal server error	Include request_id when reporting.
503	Public API is disabled	Feature flag is off on this environment (emergency kill-switch). Contact support or check the status page.

Decision matrix — retry or fail?

Condition	Action
429	Retry. Honor Retry-After.
500 with error: "Remediation generation failed"	Retry up to 3 times with exponential backoff.
500 other	Surface to operator with request_id. Do not loop.
503	Stop. Check status page. Resume manually.
4xx other than 429	Fix the request. Do not retry.
Network errors / TCP resets	Retry up to 3 times with exponential backoff.

Next steps

• Rate limits and retries
• Sign requests with HMAC
• Support and contact