Errors and status codes¶
All Xref API responses use a consistent JSON envelope for both successful and error responses.
Response envelope¶
| Field | Type | Description |
|---|---|---|
data |
object | array | null | The successful payload. null on error responses. |
status_message |
string | Coarse-grained status: ok, client_error, or server_error. |
message |
string | Human-readable detail. Empty on success; populated for errors. |
For JSON responses, the HTTP status code and status_message always align.
Use the status code to branch your logic; use message for human-readable
error detail.
Status code matrix¶
| Status | status_message |
Meaning | Retry? |
|---|---|---|---|
200 |
ok |
Successful read. | — |
201 |
ok |
Successful create (POST /v1/requests). |
— |
400 |
client_error |
Validation failure — missing/invalid field, bad JSON, schema mismatch. Invalid status and id query values on GET /v1/packages are ignored, not rejected. |
Fix the body, then retry. |
401 |
client_error |
Missing or invalid X-Xref-API-Key / X-Xref-User-Email headers, or invalid / expired ?t= report token. |
Fix the headers or re-query for a fresh token, then retry. |
403 |
client_error |
The user is not a member of the organisation, the email is unknown or inactive, the user lacks package access for this action, is Support trying to create, is a Contributor reading or downloading someone else's request, or the organisation has no credits or an inactive subscription. | Check package access, credits, and subscription, then retry. |
404 |
client_error |
The package, request, or report was not found for this organisation. | Don't retry — the resource doesn't exist for this organisation. |
405 |
client_error |
HTTP method is not allowed on this path. The body uses the standard JSON envelope. | Use a documented method for the path. |
422 |
client_error |
Reserved. v1 emits 400 for all validation failures. Future versions may use 422 to distinguish semantic from syntactic validation. |
Fix the body, then retry. |
429 |
client_error |
Per-API-key throttle exceeded. Retry-After header included. |
Wait Retry-After seconds, then retry. |
5xx |
server_error |
Internal error; the request log carries a trace id. | Retry with backoff. Treat the outcome as unknown for POST /v1/requests. |
Examples¶
200 OK — success¶
201 Created — request accepted¶
{
"data": {
"request_id": "9b2a14ee-9d0e-4d3a-aff2-7f68c19f3f3a",
"status": "RECEIVED"
},
"status_message": "ok",
"message": ""
}
400 Bad Request — validation failure¶
{
"data": null,
"status_message": "client_error",
"message": "recipient.email must be a valid email address"
}
401 Unauthorized — missing or invalid authentication¶
{
"data": null,
"status_message": "client_error",
"message": "Missing X-Xref-Api-Key or X-Xref-User-Email"
}
403 Forbidden — user not permitted or plan exhausted¶
{
"data": null,
"status_message": "client_error",
"message": "Actor is not a member of the organisation"
}
{
"data": null,
"status_message": "client_error",
"message": "You are not permitted to view this package."
}
{
"data": null,
"status_message": "client_error",
"message": "You are not permitted to create requests."
}
{
"data": null,
"status_message": "client_error",
"message": "You are not permitted to create requests using this package."
}
{
"data": null,
"status_message": "client_error",
"message": "You are not permitted to view this request."
}
{
"data": null,
"status_message": "client_error",
"message": "You are not permitted to download this report."
}
{
"data": null,
"status_message": "client_error",
"message": "Organisation has no credits remaining"
}
{
"data": null,
"status_message": "client_error",
"message": "Organisation subscription is not active"
}
404 Not Found — package or request not visible¶
429 Too Many Requests — throttled¶
Headers:
Body:
The Retry-After value is the number of seconds remaining in the breached
window (per-minute or per-hour, whichever was hit first).
5xx Server Error — internal error¶
A 5xx response indicates that the server was unable to process the request.
GET requests can be retried. For
POST /v1/requests, see
Idempotency and retries
before retrying.