Docs
Errors

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

FieldContent
typeurn:praxis:problem: followed by the code
titleA short summary
statusThe HTTP status
codeThe stable, machine-readable code
detailAn explanation, when there is one
requestIdThe request's X-Request-Id
issuesUp 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:

Request
GET /api/v1/intelligence/view?window=3000 HTTP/1.1
Authorization: Bearer $PRAXIS_TOKEN
X-Request-Id: weekly-review
Response: 400 Bad Request
{
  "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

StatusCodeCauseWhat to do
400invalid-requestInput that violates the contract or a rule, with issues when they can be locatedCorrect the input named in issues
400malformed-jsonA body that is not valid JSON, or an invalid Content-LengthSend valid JSON
401unauthorizedMissing or invalid credentialsGet a fresh access token
403forbiddenA verified caller without the operation's capabilityUse an identity that holds the capability
403origin-not-allowedA browser origin that is neither the API's own nor approvedCall from an approved origin
404not-foundAn unknown object, actor, indicator, index, risk, source or data revisionCheck the identifier in GET /meta or GET /objects
413payload-too-largeA body over the operation's limitSend a smaller body
415unsupported-media-typeA body that is not uncompressed application/jsonSend Content-Type: application/json
500internal-errorAn unexpected failure; the response holds no internal detailRetry later, and report the requestId
503storage-unavailableThe database is unreachable or did not complete the operation in timeRetry with backoff
503source-unavailableNo source has been synchronized yetRetry after the first synchronization
503overloadedThe instance is computing as much uncached work as it admitsRetry 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.