API errors and status codes

Insights endpoints return errors in one consistent shape, so a single handler covers every endpoint. PurpleTRAC does not follow it yet, and that is covered at the bottom of this page.

The error body

{
  "status": 400,
  "title": "Timestamp End value not supplied",
  "detail": "The timestamp_end parameter was included in the request but no value was supplied.",
  "field": "timestamp_end",
  "resource_uri": "/zone-port-insights/v1/zone-and-port-traffic/ID/266ea41d-adf5-480b-af50-15b940c2b846",
  "request_id": "66ea41d0-adf5-480b-af50-15b940c2b846"
}

Field	Always present	What it gives you
`status`	Yes	The HTTP status, repeated in the body so a logged payload is self-describing
`title`	Yes	Short summary of what went wrong
`detail`	Yes	The specific problem, usually enough to fix it without contacting anyone
`request_id`	Yes	Quote this to support. It identifies your exact request
`field`	When relevant	The request parameter at fault
`resource_uri`	When relevant	The path you called
`documentation`	Occasionally	A link to the relevant page

detail and field together resolve most 400s. Read those two first.

Handling errors well

Branch on status, not on title

We reword titles for clarity. Status codes are contractual.

Show detail to whoever can act on it

We write detail for a person to read. Surface it instead of substituting a generic message of your own.

Retry only 429 and 5xx, with backoff

Retrying a 400 or a 422 sends the same broken request again. Retrying a 409 creates a duplicate.

Log request_id and X-Correlation-Id on every failure

Every response carries an X-Correlation-Id header. With that and the request_id, support can find your request without asking you to reproduce it.

Status codes

400 Bad Request: the request was malformed

Missing required parameters, invalid values, malformed JSON, or a bad date format.

{
  "status": 400,
  "title": "Timestamp End value not supplied",
  "detail": "The timestamp_end parameter was included in the request but no value was supplied.",
  "field": "timestamp_end"
}

Read field, fix that parameter. Do not retry unchanged.

401 Unauthorized: credentials missing, invalid or expired

403 Forbidden: authenticated, but not permitted

404 Not Found: no such resource

405 Method Not Allowed: wrong verb

409 Conflict: it already exists

422 Unprocessable Entity: well-formed but invalid

429 Too Many Requests: slow down

500 Internal Server Error: our fault

PurpleTRAC errors differ

PurpleTRAC predates the format above and returns errors in several shapes, some of them not JSON. We are consolidating it onto the standard format. Until then, code defensively against these.

Shape	Example	Where
String under `error`	`{"error": "Request is not valid JSON."}`	Screening, invalid filters and ordering
Object under `error`	`{"error": {"additional_entities": "Field cannot be bigger than 10 entities."}}`	Registration validation
Field-keyed object	`{"transaction": {"__all__": "Please add all required fields and values."}}`	Transaction updates
Coded conflict	`{"error_code": "DUPLICATE_FOUND", "error_info": {…}, "error_message": "Duplicate entry found"}`	Duplicate transactions
Plain text	`GET/POST/PUT/PATCH/DELETE not allowed`	Unsupported methods
Empty body	no content at all	Transaction not found, report not ready

Practical advice for PurpleTRAC

Do not parse PurpleTRAC error bodies to decide what happened. Branch on the HTTP status, treat the body as a message for a person, and expect an empty body to be a valid outcome.

Getting help

Contact Pole Star support with the request_id from the error body and the X-Correlation-Id header from the response. With both, support can look the request up instead of asking you to reproduce it.

Errors & Status Codes

The error body#

Handling errors well#

Status codes#

PurpleTRAC errors differ#

Getting help#

The error body

Handling errors well

Status codes

PurpleTRAC errors differ

Getting help