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
404	`E_NOT_FOUND`	A company or customer does not exist, or belongs to another tenant — the two are deliberately indistinguishable. Returned by Get company, the signing endpoints, and Get customer. Most other company-scoped endpoints return `E_COMPANY_NOT_FOUND` for the same situation
404	`E_COMPANY_NOT_FOUND`	The company does not exist, or is not owned by your tenant — same meaning as `E_NOT_FOUND`, different code. Returned by the documents, compliance calendar, required actions, annual report and playground endpoints
404	`E_CUSTOMER_NOT_FOUND`	No customer with this `doolaCustomerId` belongs to your tenant. Returned by Create company
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 principal that is not your tenant’s customer — another tenant’s customer, a legacy customer with no tenant, or a non-customer such as a partner dashboard user. Only an email already registered as your own customer merges (`200`, `created: false`)
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`)

Industry errors

Returned only by Create company. The Choosing an industry guide has the full context.

HTTP	Code	Meaning
400	`E_VALIDATION_FAILED`	`industry` missing, blank, or not in the NAICS reference; the field detail carries `E_INDUSTRY_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`

Required action errors

Returned by the required-action reads and the resolution endpoint. The Required actions guide has the full context.

HTTP	Code	Meaning
400	`E_VALIDATION_FAILED`	`actionCode` missing, or `nameOptions` missing, empty, more than three, or carrying an unrecognised `entityTypeEnding`; the field detail names the rule
400	`E_REQUIRED_ACTION_CODE_MISMATCH`	`actionCode` does not match the action being resolved
400	`E_NAME_OPTIONS_INVALID`	A recognised ending that does not belong to the company’s entity type
404	`E_REQUIRED_ACTION_NOT_FOUND`	No action with this ID on this company, including one that belongs to another partner
404	`E_COMPANY_NOT_FOUND`	No company with this ID belongs to your tenant
409	`E_REQUIRED_ACTION_CLOSED`	The action is already resolved or rejected and never reopens
422	`E_REQUIRED_ACTION_NOT_RESOLVABLE`	The action is resolved by another flow, such as an SS-4 re-signature

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. The same code also covers customers outside your tenant on Get customer — see the global reference
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. an SS-4 for a US company, or a Form 8821 without an expedited EIN and without an open Form 8821 request)

Annual report errors

Returned by the annual-report endpoints under a company’s compliance surface. The Annual report requirements and Annual report fee guides have the full context.

HTTP	Code	Meaning
400	`E_VALIDATION_FAILED`	`fiscalYear` is outside 2000–2100; the field detail names the range
400	`E_VALIDATION_FAILED`	On the fee endpoint: an answer is missing its `fieldId`, or a `fieldId` is answered twice; the field detail names the field
400	`E_MALFORMED_JSON`	The fee request body is not parseable JSON
404	`E_COMPANY_NOT_FOUND`	No company with this ID belongs to your tenant
422	`E_STATE_NOT_SUPPORTED`	doola holds no annual-report data for the company’s state and entity type. Should not occur for a company created through this API: every state and DC is covered for both entity types. A state that files no annual report is not this error — it answers 200 with `filingRequired: false`

Get started

Core concepts

Reference

API reference

Help

Updates

Response shape

Global error reference

Industry errors

Expedited EIN errors

Required action errors

Signature errors

Annual report errors

​Response shape

​Global error reference

​Industry errors

​Expedited EIN errors

​Required action errors

​Signature errors

​Annual report errors

Response shape

Global error reference

Industry errors

Expedited EIN errors

Required action errors

Signature errors

Annual report errors