Errors
Problem details, every error code with its cause, and how to retry or correct a refused request.
Every error is a problem document in the format of RFC 9457, with the media type application/problem+json. Branch on its code, which is stable; the title and detail are for people.
The problem document
| Field | Content |
|---|---|
type | urn:praxis:problem: followed by the code |
title | A short summary |
status | The HTTP status |
code | The stable, machine-readable code |
detail | An explanation, when there is one |
requestId | The request's X-Request-Id |
issues | Up to 100 located problems, each with a path and a message, when they can be located |
A request outside the lens limits, and its answer:
GET /api/v1/intelligence/view?window=3000 HTTP/1.1
Authorization: Bearer $PRAXIS_TOKEN
X-Request-Id: weekly-review{
"type": "urn:praxis:problem:invalid-request",
"title": "Invalid request",
"status": 400,
"code": "invalid-request",
"issues": [
{ "path": "window", "message": "Too big: expected number to be <=1830" }
],
"requestId": "weekly-review"
}Codes
| Status | Code | Cause | What to do |
|---|---|---|---|
| 400 | invalid-request | Input that violates the contract or a rule, with issues when they can be located | Correct the input named in issues |
| 400 | malformed-json | A body that is not valid JSON, or an invalid Content-Length | Send valid JSON |
| 401 | unauthorized | Missing or invalid credentials | Get a fresh access token |
| 403 | forbidden | A verified caller without the operation's capability | Use an identity that holds the capability |
| 403 | origin-not-allowed | A browser origin that is neither the API's own nor approved | Call from an approved origin |
| 404 | not-found | An unknown object, actor, indicator, index, risk, source or data revision | Check the identifier in GET /meta or GET /objects |
| 413 | payload-too-large | A body over the operation's limit | Send a smaller body |
| 415 | unsupported-media-type | A body that is not uncompressed application/json | Send Content-Type: application/json |
| 500 | internal-error | An unexpected failure; the response holds no internal detail | Retry later, and report the requestId |
| 503 | storage-unavailable | The database is unreachable or did not complete the operation in time | Retry with backoff |
| 503 | source-unavailable | No source has been synchronized yet | Retry after the first synchronization |
| 503 | overloaded | The instance is computing as much uncached work as it admits | Retry after the Retry-After seconds |
The OpenAPI document lists the problems each operation can produce.
Retrying
Retry only 503 responses, and 500 once. Wait the Retry-After header's seconds when it is present, and back off exponentially otherwise. A 4xx response will not succeed unchanged; correct the request instead.
Send your own X-Request-Id on every request and log it. Every response and every problem carries it, so a failure can be traced to the exact request.