Errors

Response shape

Every response uses the same envelope. On success, payload holds the result and error is null. The one exception is a successful Confirm payment, which answers 200 with an empty body.

{
  "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": "4bf92f3577b34da6a3ce929d0e0e4736",
    "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.

Request IDs

Every response from doola’s API servers, success or failure, carries an x-request-id header. On a failure, error.requestId holds the same value. It is 32 lowercase hex characters and identifies the request’s trace. Log it with your own record of the call. When you contact doola support about a request, quote this id and support can find that trace on our side. Never use it as an idempotency or deduplication key: use Idempotency-Key for that. It identifies the request’s trace and is not guaranteed to be unique per call, so use it for correlation only. An x-request-id header you send is not echoed back.

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_VALIDATION_FAILED`	One or more fields failed validation. Each failing field is listed under `error.fields` with its own `code` (see Response shape). On a list endpoint, a negative `page` or a `size` below 1 reports `E_PAGINATION_INVALID` on `fields.page` or `fields.size`. 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 deactivated. Returned to Partner Portal sessions, on reads and writes. Deactivation also revokes every API key, so API-key calls get `401 E_AUTH_INVALID` instead
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, Get customer, and Annual Report Filing when no such report exists for the company. 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 Filing 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 E_VALIDATION_FAILED`)

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, or not in the NAICS reference; the field detail carries `E_INDUSTRY_INVALID` on `industry`

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 an SSN in a valid format; ITIN-only companies remain eligible for expedited EIN
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 by the signing endpoints. The SS-4 and Form 8821 signing guide has the full context.

HTTP	Code	Meaning
400	`E_DOCUMENT_TYPE_NOT_SUPPORTED`	The document type cannot be signed through this endpoint
400	`E_RESPONSIBLE_PARTY_INVALID`	The responsible party’s name or email is missing, or the name cannot be printed on the form
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
409	`E_COMPANY_CANCELLED`	An SDK formation doola cancelled before its payment was confirmed. Nothing is left to sign
410	`E_SIGNATURE_URL_EXPIRED`	Signing link expired or tampered with; request a new session
422	`E_FORMATION_AWAITING_PAYMENT`	An SDK formation still waiting on your payment confirmation. Signing opens once you confirm
422	`E_FORMATION_NOT_ELIGIBLE`	The company does not require this document (e.g. SS-4 is exempt because someone supplies an SSN in a valid format, or neither the formation workflow nor an open Form 8821 request requires Form 8821). An ITIN does not grant the SS-4 exemption
503	`E_SIGNATURE_PROVIDER_UNAVAILABLE`	The signing provider did not respond; retry with backoff. No session was created

Annual Report Filing errors

Returned by the Annual Report Filing endpoints. The guide lists which endpoint returns each one.

HTTP	Code	Meaning
400	`E_VALIDATION_FAILED`	On the requirements: `fiscalYear` is outside 2000–2100. On the submission: an answer or correction was refused, keyed under `fields` by its `fieldId`
404	`E_COMPANY_NOT_FOUND`	No company with this ID belongs to your tenant
404	`E_NOT_FOUND`	Reading one report or confirming it: no such report exists for that company. A missing report and one that belongs to another company get the same answer
409	`E_ANNUAL_REPORT_ALREADY_EXISTS`	Submitting: the report for that fiscal year is past `FILLED` (confirmed, being filed, or already filed), so it is not replaced. While it is still `FILLED`, a second submission replaces it
409	`E_RESOURCE_CONFLICT`	Confirming: the report is in a status that cannot be confirmed
422	`E_STATE_NOT_SUPPORTED`	doola holds no annual report data for the company’s state and entity type, which should not occur for a company created through this API. Also returned when submitting for a state that files no annual report. On the two reads, a state that files no report is not this error: it answers `200` with `isFilingRequired: false`

Embedded SDK errors

Returned by the two Partner API endpoints an Embedded SDK integration calls from your server. SDK errors covers what the SDK reports in the browser.

HTTP	Code	Meaning
409	`E_RESOURCE_CONFLICT`	Creating a customer session: the email’s customer is already bound to a different `externalCustomerId`, this `externalCustomerId` belongs to another customer, or an older customer cannot take a new email
409	`E_CUSTOMER_REVOKED`	Creating a customer session: doola deactivated this customer
404	`E_NOT_FOUND`	Confirming payment: no company with this ID belongs to your tenant
409	`E_COMPANY_CANCELLED`	Confirming payment: doola cancelled this formation before its payment was confirmed. The payment was not applied, so refund the founder

Creating a customer session also returns 409 E_EMAIL_IN_USE from the global reference, and is limited to 600 sessions a minute per tenant (429 E_RATE_LIMITED).

Get started

Core concepts

Reference

API reference

Help

Updates

Response shape

Request IDs

Global error reference

Industry errors

Expedited EIN errors

Required action errors

Signature errors

Annual Report Filing errors

Embedded SDK errors

​Response shape

​Request IDs

​Global error reference

​Industry errors

​Expedited EIN errors

​Required action errors

​Signature errors

​Annual Report Filing errors

​Embedded SDK errors

Response shape

Request IDs

Global error reference

Industry errors

Expedited EIN errors

Required action errors

Signature errors

Annual Report Filing errors

Embedded SDK errors