Errors

Response shape

Every response uses the same envelope. On success, payload holds the result and error is 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.

{
  "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"
      }
    }
  }
}

Branch on error.code, not on message. Codes are stable; messages may change.

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 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 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)

Get started

Core concepts

Reference

API reference

Help

Updates

Response shape

Global error reference

Expedited EIN errors

Signature errors

​Response shape

​Global error reference

​Expedited EIN errors

​Signature errors

Response shape

Global error reference

Expedited EIN errors

Signature errors