Errors - FaWCOS Developers

The API uses standard HTTP status codes. 2xx means success, 4xx means the request could not be completed as sent, and 5xx means something went wrong on our side.

The error object

Every error has the same shape:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request",
    "details": [
      { "location": "body", "path": "purpose", "message": "Required" }
    ]
  }
}

Field	Meaning
`code`	A short, stable identifier. Branch on this.
`message`	A human-readable explanation. It may be reworded, so do not match on it.
`details`	Optional extra information. Its shape depends on the code.

Request ids

Every response from the API, errors included, carries an X-Request-Id header such as req_3f9c…. Quote it when you contact support and we can find the exact request.

Codes

HTTP	`code`	What it means	What to do
400	`validation_error`	The body, query or path failed validation. `details` lists each problem.	Fix the request. Do not retry unchanged.
401	`unauthorized`	The key is missing, malformed, unknown, revoked or expired.	Check the `x-api-key` header and that the key is still active.
403	`live_access_not_approved`	A live key was used, but live access is not approved or is suspended.	Finish going live, or use a test key.
403	`insufficient_scope`	The key lacks the scope this endpoint needs. `details.required` names it.	Create a key with the scope. See Permissions.
403	`access_denied`	Your organisation is not active.	Contact FaWCOS support.
404	`not_found`	No such endpoint or resource.	Check the path and id.
429	`rate_limited`	A per-minute or daily limit was reached.	Back off and retry. See Rate limits.
500	`internal_error`	Something went wrong on our side.	Retry with backoff. If it persists, send us the request id.

This list covers the endpoints that are live today. It grows as endpoints are released, and each new code is added here first.

Handling errors

Treat 4xx as final unless the table says otherwise. Retrying an unchanged request will not help.
Retry 429 and 5xx with exponential backoff and jitter.
A timeout or 5xx on a request that changes something leaves the outcome uncertain. Check the state of the thing you were changing before repeating it.
Log the X-Request-Id of every failed request.