Skip to main content
Pre-release — contact your Fortary account team for access.
Every error response uses the same JSON envelope and a standard HTTP status code, so you can handle failures consistently.

​
The error envelope

All errors return a single top-level error object: 
{
  "error": {
    "type": "not_found",
    "code": "not_found",
    "message": "No vault matches that identifier for this credential.",
    "details": { "field": "vaultId" },
    "correlationId": "b3f1c9a2-7d44-4e90-9c1a-2f0e8d6a5b13",
    "docUrl": "https://docs.fortary.io/errors/not_found"
  }
}
FieldDescription
typeA broad, stable category — one of invalid_request, unauthorized, forbidden, not_found, rate_limited, internal_error. Good for branching your error handling.
codeA specific, stable machine-readable code. Use this for precise handling.
messageA human-readable explanation. May be reworded between releases — don’t match on it.
detailsOptional structured context about the error (for example, which field was at fault).
correlationIdA unique identifier for this request. Quote it when contacting support. It mirrors the X-Request-Id response header.
docUrlA link to the documentation page for this code, at https://docs.fortary.io/errors/<code>.
Branch on type (or code) and the HTTP status, never on message. The codes are part of the contract; the wording is not.

​
HTTP status codes

For the read-only v1 API you’ll encounter:
StatusMeaning
200Success — body returned.
204Success — no body.
400Malformed request — bad JSON, a missing or wrong-typed parameter, or an unsupported filter.
401Missing, invalid, expired, or revoked credential.
403Valid credential, but it lacks the required scope or access for this operation.
404The resource doesn’t exist or isn’t visible to this credential. See Authorization.
413Request body too large.
422The request was well-formed but a value was semantically invalid.
429Rate limited — back off using the response headers. See Rate limiting.
500An unexpected error on our side. Safe to retry after a short wait.
503A dependency is temporarily unavailable; a Retry-After header tells you when to retry.

​
Per-code reference

Each error includes a docUrl that points to a page for that specific code — its cause and how to resolve it — at https://docs.fortary.io/errors/<code>. Pages for the common error codes are available now; per-resource codes are added as the API surface ships.

​
Request identifiers for support

Every response — success or error — carries an X-Request-Id header, and error bodies mirror it as correlationId. If you need help with a specific request, include that value: it lets support trace exactly what happened. If you send your own X-Request-Id header on a request, it’s echoed back to you in a separate clientRequestId field for your own correlation; the authoritative X-Request-Id is always generated by the API.