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

# Scribe API errors: status codes and error format

> Understand Scribe API errors: the JSON error envelope, validation details, and what each HTTP status code from 401 to 422 means.

The Scribe API uses conventional HTTP status codes and returns a consistent JSON error envelope, so you can handle failures the same way across every endpoint.

## Error format

Every error response contains an `error` object:

```json theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "blank",
    "message": "Name can't be blank."
  }
}
```

| Field     | Description                                                       |
| --------- | ----------------------------------------------------------------- |
| `type`    | The category of error, such as `validation_error` or `not_found`. |
| `code`    | A short, stable identifier for the specific error.                |
| `message` | A human-readable explanation.                                     |

### Validation errors

When a request fails validation, the response also includes a `details` array that pinpoints each invalid field:

```json theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "invalid",
    "message": "The teammate could not be saved."
  },
  "details": [
    { "field": "email", "code": "invalid", "message": "Address is invalid." }
  ]
}
```

## Status codes

| Status                     | Meaning                                                                                                     |
| -------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `200 OK`                   | The request succeeded.                                                                                      |
| `201 Created`              | The resource was created.                                                                                   |
| `204 No Content`           | The request succeeded with no response body, for example after a delete.                                    |
| `401 Unauthorized`         | The API key is missing or invalid. See [Authentication](/api-reference/authentication).                     |
| `403 Forbidden`            | The key lacks the required scope, or the feature is not available on your plan.                             |
| `404 Not Found`            | The resource does not exist, or it belongs to another workspace.                                            |
| `409 Conflict`             | The request conflicts with the current state, for example deleting a folder that still contains signatures. |
| `422 Unprocessable Entity` | The request was understood but failed validation. Check the `details` array.                                |

<Note>
  Scribe returns `404` rather than `403` when a resource belongs to another workspace, so a key can never confirm whether a resource it cannot access exists.
</Note>

## Handle errors gracefully

* Treat any non-`2xx` status as a failure, and read `error.type` and `error.code` to decide what to do.
* For `422`, surface the `details` array so the cause can be corrected field by field.
* For `401` and `403`, check that the key is valid and carries the scopes the endpoint requires.
* For `409`, resolve the conflicting state first, for example empty a folder before deleting it.