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

# Errors

> The error envelope and the global error codes returned by the doola Partner API.

## Response shape

Every response uses the same envelope. On success, `payload` holds the result and `error` is `null`.

```json theme={null}
{
  "payload": { },
  "error": null
}
```

On failure, `payload` is `null` and `error` carries a machine readable `code`, a human readable `message`, a `requestId`, and, for validation failures, per field details.

```json theme={null}
{
  "payload": null,
  "error": {
    "code": "E_VALIDATION_FAILED",
    "message": "one or more fields are invalid",
    "requestId": "3D2mMaLHsT60sI5qyeHuBlS9TEM",
    "fields": {
      "doolaCustomerId": {
        "code": "E_CUSTOMER_ID_REQUIRED",
        "message": "customer id is required"
      }
    }
  }
}
```

<Tip>
  Branch on `error.code`, not on `message`. Codes are stable; messages may change.
</Tip>

## Global error reference

These can be returned by any endpoint. Endpoint specific codes are documented in the API reference.

| HTTP | Code                         | Meaning                                                                                                                                                                                       |
| ---- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | `E_IDEMPOTENCY_KEY_REQUIRED` | Missing `Idempotency-Key` header                                                                                                                                                              |
| 400  | `E_IDEMPOTENCY_KEY_TOO_LONG` | `Idempotency-Key` exceeds the max length                                                                                                                                                      |
| 400  | `E_MALFORMED_JSON`           | Request body is not parseable JSON                                                                                                                                                            |
| 400  | `E_REQUEST_BODY_INVALID`     | Body is missing, malformed, or the wrong shape                                                                                                                                                |
| 400  | `E_PAGINATION_INVALID`       | Field detail on a list endpoint when `page` is negative or `size` is below 1. An oversized `size` is capped at 100 rather than rejected                                                       |
| 401  | `E_AUTH_MISSING`             | No `Authorization` header present                                                                                                                                                             |
| 401  | `E_AUTH_INVALID`             | Invalid or expired key, or a key used on the wrong environment                                                                                                                                |
| 403  | `E_TENANT_SUSPENDED`         | Partner tenant is suspended; writes are rejected                                                                                                                                              |
| 405  | `E_METHOD_NOT_ALLOWED`       | HTTP method not allowed for this resource                                                                                                                                                     |
| 409  | `E_IDEMPOTENCY_IN_PROGRESS`  | Same idempotency key is still processing                                                                                                                                                      |
| 409  | `E_IDEMPOTENCY_KEY_REUSED`   | Same idempotency key used with a different body                                                                                                                                               |
| 409  | `E_EMAIL_IN_USE`             | Email already belongs to a non-customer principal (e.g. a partner dashboard user); one email cannot be both                                                                                   |
| 429  | `E_RATE_LIMITED`             | Too many requests; the rate limit was exceeded. Back off and retry after the `Retry-After` response header (seconds)                                                                          |
| 500  | `E_INTERNAL`                 | Unexpected server error                                                                                                                                                                       |
| 503  | `E_SEARCH_UNAVAILABLE`       | The search backend behind the list endpoints is unavailable. Retry with backoff — this signals a doola-side outage, never bad input (invalid pagination is a 400, see `E_PAGINATION_INVALID`) |

## Expedited EIN errors

Returned only by Create company when `requestedServices` is present. The [Expedited EIN](/api/expedited-ein#errors) guide has the full context.

| HTTP | Code                           | Meaning                                                                                    |
| ---- | ------------------------------ | ------------------------------------------------------------------------------------------ |
| 400  | `E_EXPEDITED_EIN_NOT_ELIGIBLE` | Someone on the company supplies a US tax ID; expedited EIN is non-US only                  |
| 400  | `E_VALIDATION_FAILED`          | Invalid `requestedServices` shape; the field detail carries `E_REQUESTED_SERVICES_INVALID` |

## Signature errors

Returned only by the non-US founder signing endpoints. The [Non-US founders](/api/non-us-formation#errors) guide has the full context.

| HTTP | Code                            | Meaning                                                                                               |
| ---- | ------------------------------- | ----------------------------------------------------------------------------------------------------- |
| 400  | `E_DOCUMENT_TYPE_NOT_SUPPORTED` | The document type cannot be signed through this endpoint                                              |
| 404  | `E_NOT_FOUND`                   | No company with this ID belongs to your tenant                                                        |
| 409  | `E_DOCUMENT_ALREADY_SIGNED`     | The requested document (SS-4 or Form 8821) is already signed                                          |
| 410  | `E_SIGNATURE_URL_EXPIRED`       | Signing link expired, voided, or tampered with; request a new session                                 |
| 422  | `E_FORMATION_NOT_ELIGIBLE`      | The company does not require this document (e.g. a US company, or Form 8821 without an expedited EIN) |