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

# Errors

> Status codes, error body format, and the machine-readable error codes each endpoint can return.

Errors follow a single body shape across the API:

```json theme={null}
{
  "status": 409,
  "code": "AGENT_NAME_TAKEN",
  "message": "Agent name already exists in this workspace",
  "timestamp": "2026-05-25T14:30:12.234567Z"
}
```

| Field       | Notes                                                                |
| ----------- | -------------------------------------------------------------------- |
| `status`    | Echo of the HTTP status. Always matches the response code.           |
| `code`      | Machine-readable, stable identifier — safe to switch on.             |
| `message`   | Human-readable explanation. Wording may change; don't pattern-match. |
| `timestamp` | Server time the error occurred. Useful for support tickets.          |

## Status code reference

| Status                | When you'll see it                                                                                                                         |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `200` / `201` / `204` | Success. `201` for creates, `204` for deletes with no body.                                                                                |
| `400`                 | Validation failed, malformed JSON, unknown fields, invalid pagination, immutable field touched.                                            |
| `401`                 | Missing or invalid API key. See [Authentication](/en/api-reference/authentication).                                                        |
| `403`                 | Workspace lacks permission for this operation (e.g. trying to use a feature not in the plan).                                              |
| `404`                 | Resource not found. Either the ID doesn't exist or it belongs to a different workspace.                                                    |
| `408`                 | Sync agent message timed out — increase `timeoutSeconds` (max 300) or switch to the streaming endpoint.                                    |
| `409`                 | Conflict — duplicate name, resource already linked, state transition not allowed.                                                          |
| `422`                 | Business rule violation — e.g. plan limit reached, cycle detected, channel config blocked.                                                 |
| `429`                 | Rate or quota limit hit. Wait and retry.                                                                                                   |
| `500`                 | Server error. Should not happen — file a bug with the `timestamp` from the body.                                                           |
| `502`                 | Upstream service unreachable (the request reached our gateway, but a downstream — Composio, payment provider — failed). Usually transient. |

## Common error codes

These are the codes you'll see most often. The full set is documented per endpoint in the API Reference.

### Authentication

* `MISSING_API_KEY`, `INVALID_API_KEY_FORMAT`, `INVALID_API_KEY` — all `401`.

### Validation

* `VALIDATION_ERROR` — `400`. Body has invalid fields, bad enum value, or unknown property.
* `MALFORMED_JSON` — `400`. Request body isn't valid JSON.
* `IMMUTABLE_FIELD` — `400`. Tried to change a field that can't be edited after creation (e.g. `toolType`).

### Resource state

* `AGENT_NOT_FOUND`, `CLIENT_NOT_FOUND`, `KNOWLEDGE_SOURCE_NOT_FOUND`, etc. — `404`.
* `ALREADY_LINKED`, `AGENT_NAME_TAKEN`, `SKILL_NAME_TAKEN`, `EXTERNAL_MCP_NAME_TAKEN` — `409`.

### Business rules

* `NO_DRAFT_VERSION` — `409`. The agent has no draft to modify; publish first or create a new draft.
* `SUB_AGENT_CYCLE` — `422`. Linking would create a cycle (A → B → A).
* `OAUTH_NOT_SUPPORTED_VIA_API` — `422`. OAuth registration requires the Studio web flow.
* `CHANNEL_CONFIG_NOT_ALLOWED_VIA_API` — `422`. WhatsApp config requires Meta OAuth in Studio web.
* `HTTP_TOOL_LIMIT_REACHED` — `422`. Workspace is at the plan limit.

## Retry guidance

| Status                        | Retry?                                                                              |
| ----------------------------- | ----------------------------------------------------------------------------------- |
| `400` / `404` / `409` / `422` | **No.** Fix the request.                                                            |
| `401`                         | **No.** Fix the key.                                                                |
| `408`                         | **Sometimes.** Increase `timeoutSeconds` or use streaming.                          |
| `429`                         | **Yes**, with exponential backoff. Start at 1s, cap at 30s.                         |
| `500` / `502`                 | **Yes**, with exponential backoff. If a `500` persists, it's a bug — file a report. |

Idempotent operations (`GET`, `DELETE`) are always safe to retry. For `POST` / `PATCH`, retry only on transient failures (`429`, `502`, network errors) to avoid double-creates.