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

# Errors

> Status codes and error envelope shape used across the unified API launch surface.

## Envelope

Every error response uses the same shape:

```json theme={null}
{
  "errorCode": "VALIDATION_ERROR",
  "message": "Human-readable description.",
  "details": { "...": "optional, error-specific" }
}
```

The `errorCode` is stable across releases. Switch on it programmatically. The `message` is meant for humans and may change.

## Status codes

| Code  | Meaning                                                                                       |
| ----- | --------------------------------------------------------------------------------------------- |
| `200` | Success                                                                                       |
| `202` | Accepted — work started asynchronously, such as Brand Kit extraction or email processing      |
| `204` | Success, no content                                                                           |
| `400` | Bad request — payload validation failed                                                       |
| `401` | Missing or invalid `x-api-key`                                                                |
| `403` | Key valid but lacks the required scope                                                        |
| `404` | Resource not found, or belongs to a different organization                                    |
| `409` | Conflict — concurrent retry, idempotency lock held, or terminal-state operation               |
| `410` | Gone — a temporary resource or token has expired                                              |
| `422` | Unprocessable — semantic validation failed (e.g. template incomplete, idempotency key reused) |
| `429` | Rate limited                                                                                  |
| `501` | Not implemented                                                                               |

## Common error codes

* `MISSING_CREDENTIAL` - no supported credential was supplied (401).
* `INVALID_API_KEY` - `x-api-key` is invalid or revoked (401).
* `INSUFFICIENT_SCOPE` or `API_KEY_SCOPE_INSUFFICIENT` - key valid but missing a required scope (403). Includes `required` field listing the needed scopes.
* `NOT_FOUND` - the resource doesn't exist or belongs to another organization (404). The API never reveals which.
* `IDEMPOTENCY_KEY_REUSED` - same `Idempotency-Key` header sent with a different request.
* `VALIDATION_ERROR` - the request is structurally valid but semantically rejected, such as a template missing a subject or sender profile.

## Cross-organization access

Reading or writing a resource that belongs to another organization always returns `404` — never `403`. This prevents an attacker (or a confused integration) from enumerating which IDs exist in other orgs.