Errors

Every error the API emits is an RFC 9457 Problem Details document with content type application/problem+json. There are no other error shapes.

{
  "type": "https://api.secutec.com/errors/request/invalid-cursor",
  "title": "Bad Request",
  "status": 400,
  "detail": "The cursor could not be decoded.",
  "instance": "/v1/assets"
}

Match on the type URI. It is stable across releases and is the field your error handling should branch on. title is a constant label per type, status mirrors the HTTP status code, and detail describes the individual occurrence — its wording can change, so never parse it.

On 422 responses only, an errors array lists the field-level failures:

{
  "type": "https://api.secutec.com/errors/request/validation",
  "title": "Validation Error",
  "status": 422,
  "errors": [
    { "field": "note", "message": "must be a string" }
  ]
}

Error catalog

All type URIs are relative to https://api.secutec.com/errors/.

Status	type suffix	When
400	request/invalid-cursor	The cursor value could not be decoded, or limit is out of range.
400	request/invalid-sort	An unsupported sort was requested.
400	request/invalid-filter	A filter parameter is malformed or unsupported.
400	request/invalid-status-transition	The requested status change is not allowed from the current status.
401	auth/missing-token	No Authorization header was sent.
401	auth/invalid-token	The token is malformed or its signature does not verify.
401	auth/expired-token	The token's lifetime has passed — request a new one.
401	auth/revoked-account	The service account has been disabled.
403	auth/insufficient-role	The token is valid but lacks the role the endpoint requires.
404	path/not-allowlisted	No such endpoint. Check the method and path against the API reference.
404	resource/not-found	The endpoint exists, but no resource with that id exists for your organization.
422	request/validation	The request body failed validation; see the errors array.
429	rate-limit/exceeded	Too many requests — honour the Retry-After header. See Rate limits.
500	server/internal-error	Something failed on our side. Safe to retry with backoff.

The two 404 types are deliberately distinct: path/not-allowlisted means the URL itself is wrong, resource/not-found means the URL is fine but the id in it does not exist for your organization. Clients typically treat the first as a bug in their integration and the second as normal data flow.

Status-code semantics

• 401 vs 403 — 401 means the API does not know who you are (missing, invalid or expired token); 403 means it knows exactly who you are and the answer is no.
• 400 vs 422 — 422 is reserved for request-body validation. Query parameter problems and business-rule violations are 400.

When you contact support

Every response carries an X-Request-ID header. Quote it — it lets support find the exact request in the platform's logs.