Skip to main content
Most error responses from the Infisical API share a standard JSON schema with four fields: the HTTP status, a short machine-readable identifier, a human-readable message, and a request identifier. A few protocol-specific endpoints return their protocol’s own error shape instead.

​
Response format

The standard response schema contains these four fields:
  • reqId: the identifier assigned to this request by the Infisical server; include it when reporting an issue
  • statusCode: the HTTP status code, also included in the response body for logging
  • error: a short, stable identifier for the error class that can be used to branch application logic (for example, NotFound, BadRequest, ValidationFailure, PermissionDenied, RateLimitExceeded)
  • message: a description of the error, usually a string; on a ValidationFailure returned by request-body schema validation, it can be an array of individual field-level errors instead
Some responses also include an optional details field with additional structured information about the error (for example, the input value that failed validation, or the permission that was denied). The presence and structure of details depend on the specific error.

​
Protocol-specific error shapes

A few endpoints implement well-known protocols and return the error shape those protocols define:
  • OAuth 2.0 token endpoints (for example, POST /api/v1/oauth/token) return { error, error_description } per RFC 6749 §5.2
  • SCIM endpoints (/api/v1/scim/...) return the SCIM error object (schemas, status, detail, scimType) per RFC 7644 §3.12
  • ACME endpoints (/api/v1/pki/acme/...) return application/problem+json per RFC 8555 §6.7

​
Common status codes

Here are some common error codes returned by the API: Retry a 429 response after the wait time indicated in the message field. For a 5xx response, retry idempotent requests (GET, PUT, DELETE) with exponential backoff. Don’t blindly retry a POST or PATCH on a 5xx, since the server may have completed the write before the response failed; retry only if the endpoint documents an idempotency mechanism or you can verify the operation didn’t take effect. Don’t retry a 4xx response other than 429 without changing the request first.

​
Reporting an issue

When reporting an issue, include:
  • The reqId from the response
  • The HTTP status code and the error value
  • The endpoint that was called and the approximate time of the call
The reqId contains no credentials or user data and is safe to share in tickets, chat messages, and public issue trackers.