> ## Documentation Index
> Fetch the complete documentation index at: https://infisical.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The Infisical API error response format, common HTTP status codes, and how to use the request ID when reporting an issue.

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](#protocol-specific-error-shapes) instead.

## Response format

```json theme={"dark"}
{
  "reqId": "req-abc123",
  "statusCode": 404,
  "message": "Project with ID 'ba3d4bfc-...' not found",
  "error": "NotFound"
}
```

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](#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](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2)
* **SCIM endpoints** (`/api/v1/scim/...`) return the SCIM error object (`schemas`, `status`, `detail`, `scimType`) per [RFC 7644 §3.12](https://datatracker.ietf.org/doc/html/rfc7644#section-3.12)
* **ACME endpoints** (`/api/v1/pki/acme/...`) return `application/problem+json` per [RFC 8555 §6.7](https://datatracker.ietf.org/doc/html/rfc8555#section-6.7)

## Common status codes

Here are some common error codes returned by the API:

| Status | `error` value                          | Meaning                                                                                                                                                                                                                                                       |
| ------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `BadRequest`                           | The request was well-formed but rejected by a semantic check. The `message` describes what to change.                                                                                                                                                         |
| 401    | `UnauthorizedError`                    | The access token is missing, expired, or invalid. Re-authenticate to get a new access token.                                                                                                                                                                  |
| 403    | `PermissionDenied` or `ForbiddenError` | The identity is authenticated but doesn't have a role or permission that this endpoint requires.                                                                                                                                                              |
| 404    | `NotFound`                             | The requested resource doesn't exist, or the identity doesn't have access to it. Infisical returns `404` (rather than `403`) for resources outside the identity's scope so that the API can't be used to confirm the existence of another tenant's resources. |
| 409    | `Conflict`                             | The request conflicts with the current state of the resource (for example, a duplicate name, or a state transition that isn't allowed).                                                                                                                       |
| 422    | `ValidationFailure`                    | A field in the request failed schema validation. The `message` field usually contains an array of individual field-level errors.                                                                                                                              |
| 429    | `RateLimitExceeded`                    | The applicable [rate limit](/docs/api-reference/overview/rate-limits) has been exceeded. The `message` field indicates the number of seconds to wait before retrying.                                                                                              |
| 500    | `InternalServerError`                  | An unexpected error on the Infisical server. Include the `reqId` when reporting the error.                                                                                                                                                                    |
| 504    | `GatewayTimeoutError`                  | An upstream dependency (for example, a database, an external KMS, or a gateway target) didn't respond within the configured timeout. Retrying the request is usually safe.                                                                                    |

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.