---
title: "Errors"
description: "The error body every EZGH Cloud API returns, its status codes and error codes, and which errors to retry."
---

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

# Errors

Every error response has the same JSON body:

```json
{ "error": { "code": "access_denied", "message": "You're not allowed to projects.delete" } }
```

- `code` is stable. Branch on it.
- `message` is for people and can change.
- Some errors add fields next to `code` and `message`: `issues` for `invalid_request`, `quota`
  for `quota_exceeded`, and `line` and `column` for Trails' `invalid_query`.

A validation failure lists every problem, with the path of the field:

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed",
    "issues": [{ "path": "limit", "message": "must be an integer from 1 to 100" }]
  }
}
```

## Status codes

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `invalid_request` | The body, path or query is malformed, or `limit` is out of range. |
| 400 | `invalid_cursor` | The cursor was changed, or belongs to another list, filter or organization. |
| 401 | `unauthenticated` | No credential, or one that isn't valid. |
| 403 | `access_denied` | Your policies don't allow the action. The message names it. |
| 403 | `forbidden` | Policies can't grant this, or not with this credential, for example deleting the organization with an API key. |
| 404 | `not_found` | The resource doesn't exist, its ID is malformed, or it's in an organization you don't belong to. |
| 409 | `idempotency_conflict` | The `Idempotency-Key` was used for a different request. |
| 409 | `idempotency_in_progress` | The first request with this `Idempotency-Key` hasn't finished. Has `Retry-After`. |
| 409 | `quota_exceeded` | An allocation quota is full, such as projects per organization. Has `quota`. |
| 412 | `precondition_failed` | The `If-Match` header doesn't match the resource's current `ETag`. Nothing changed. |
| 413 | `payload_too_large` | The request body is over the operation's limit. |
| 429 | `too_many_requests` | You're over a rate limit. Has `Retry-After`. |
| 429 | `quota_exceeded` | A rate, usage or concurrency quota is spent. Has `quota`. |
| 500 | `internal_error` | A problem on EZGH Cloud's side. The message is "Something went wrong". |
| 503 | `unavailable` | A service the request needs is unavailable. Has `Retry-After`. |

Operations can return their own codes as well, such as `organization_exists` and
`managed_by_scim`. Each operation's page in the API reference lists its responses.

## Organizations you don't belong to

A request for an organization you don't belong to returns `404 not_found` with the message
`Organization not found`, the same as for an organization that doesn't exist. Other people's
organizations can't be discovered by probing IDs.

## Quota errors

`quota_exceeded` has a `quota` object that names the quota (`id`), its `limit` and how much is
`used`. It never has `Retry-After`: waiting doesn't free an allocation. Delete something, or wait
for the rate window or billing period the quota describes. See [Service quotas](/quotas).

## Retrying

| Response | Retry |
| --- | --- |
| `429 too_many_requests`, `503 unavailable`, `409 idempotency_in_progress` | After the `Retry-After` seconds |
| `429 quota_exceeded`, `409 quota_exceeded` | Not until usage is below the limit |
| Other `4xx` | Not without changing the request |
| `500 internal_error`, or no response | With the same `Idempotency-Key`, where the operation takes one |

`Retry-After` is a whole number of seconds.

Source: https://docs.ezghcloud.com/api/errors/index.mdx