Error Codes

Every error_code the Dots API returns, grouped by category, with what each one means and how to respond.

This page lists the error codes returned by the Dots API and what each one means.

Error Response Shape

Every failed request returns a JSON body with success: false. Branch on error_code rather than on message: the code is stable, the message is not.

Error response

{
  "success": false,
  "message": "There are insufficient funds in the wallet",
  "error_code": "transaction-insufficient-funds"
}

Field	Description
`success`	Always `false` on an error response.
`message`	Human-readable description. Subject to change; do not parse it.
`error_code`	Stable machine-readable code. Absent on some authorization failures and on schema validation errors.
`errors`	Structured validation details, when available.

Treat an absent error_code as a generic failure of that HTTP status rather than as a distinct condition. Always handle the status code as well as the code.

Authentication Errors

Code	Description
`auth-contact-already-exists`	The provided phone number is already in use.
`auth-email-already-exists`	The provided email address is already in use.
`auth-username-already-exists`	The provided username is already in use.
`authentication-code-expired`	The authentication code has expired.
`captcha-failed`	CAPTCHA validation failed.

Validation Errors

Code	Description
`address-invalid`	The address is invalid. Check and update the address.
`external-id-already-exists`	The provided external ID is already in use.
`incomplete-business-compliance-information`	The business compliance information is incomplete.
`invalid-checkout-session-line-item`	A checkout session line item is invalid.
`invalid-date-of-birth`	The provided date of birth is invalid.
`invalid-ein`	The provided Employer Identification Number (EIN) is invalid.
`invalid-email`	The email address is invalid.
`invalid-input`	The request input is invalid.
`invalid-phone-number`	The phone number is invalid.
`invalid-phone-number-landline`	Landline phone numbers are not allowed.
`invalid-phone-number-voip`	VOIP phone numbers are not allowed.
`invalid-ssn`	The provided Social Security Number (SSN) is invalid.
`invalid-username`	The username is invalid. Usernames may only contain letters, digits, and hyphens (`-`). They must not contain swear words or protected words.
`plaid-business-name-mismatch`	The bank account name and business legal name do not match. Contact support for help.
`tin-check-failed`	The SSN or EIN did not match the provided personal information.

Invoice Errors

Code	Description
`invalid-invoice-requested-information`	The value for requested information in the invoice is invalid.
`invalid-invoice-breakdown`	The breakdown of the invoice is invalid.
`invalid-invoice-item`	The invoice item is invalid.
`invalid-invoice-item-total`	The totals of the invoice items are incorrect.

Transaction Errors

Code	Description
`ach-account-balance-check-failed`	The ACH account balance check failed.
`clawback-failed`	The clawback failed.
`duplicate-wire-amount`	A wire with the same amount was created in the last seven days. Retry with an amount at least one dollar apart.
`invalid-transaction`	The transaction is invalid.
`payout-minimum-unmet`	The payout amount does not meet the minimum.
`transaction-insufficient-funds`	There are insufficient funds in the wallet.

Idempotency Errors

Code	Description
`idempotency-error`	The request has already been processed.
`idempotent-transaction`	The transaction has already been processed.

Resource and Permission Errors

Code	Description
`inactive-organization-connection`	The organization connection is inactive.
`insufficient-permission`	The credentials lack permission for the action.
`no-organization-selected`	No organization is selected.
`no-such-resource`	The requested resource was not found.
`plan-rate-limit-exceeded`	The current plan’s rate limit has been exceeded.
`plan-restricted`	The endpoint is not available on the current plan.
`status-conflict`	The resource is in a conflicting state.

User Information Errors

Code	Description
`app-info-missing`	The app has missing or invalid information.
`banned-user`	The user is banned.
`user-info-missing`	The user has missing or invalid information.
`user-info-missing-card`	The user is missing credit card information.
`user-info-missing-cash-app`	The user is missing Cash App account information.
`user-info-missing-contact`	The user is missing contact information.
`user-limit-exceeded`	The user exceeded a payment limit or must submit a required tax form, such as a 1099, before receiving another payout.
`user-merged`	The user was merged into another user.

Returned when Dots cannot deliver a verification code. These surface on Send a Verification Token. A white-labeled integration has to handle them directly, because your UI — not a Dots-hosted Flow — owns the phone number the user typed in.

Code	Status	Description
`phone-number-invalid`	422	The phone number is not a valid destination. Re-collect the number.
`phone-number-not-sms-capable`	422	The number cannot receive SMS, typically a landline. Ask for a mobile number.
`phone-number-unsubscribed`	422	The number opted out of Dots messages. The user must use a different number or contact support.
`phone-number-temporarily-blocked`	422	The carrier is temporarily blocking the number. Retry later or use a different number.
`verification-max-attempts`	429	Too many verification attempts for this number. Wait before retrying.
`phone-number-calls-not-supported`	422	The number cannot receive a voice call. Retry without `use_voice`.
`phone-number-call-blocked`	422	The voice call was blocked. Retry without `use_voice`.

phone-number-invalid, phone-number-not-sms-capable, and phone-number-unsubscribed will not succeed on retry with the same number — prompt the user for a different one. phone-number-temporarily-blocked and verification-max-attempts are time-based and are worth retrying with backoff.

Service Errors

Code	Description
`email-send-failed`	The email could not be sent. Try again.
`pdf-generation-failed`	The PDF could not be generated. Try again.
`resource-busy`	The resource is unavailable because one or more previous requests are still being processed.
`service-unavailable`	A service was unavailable.
`sms-send-failed`	The SMS could not be sent. Try again.

Error Response Shape

Error Code Reference

Authentication

Validation

Invoice

Transaction

Idempotency

Resources and Permissions

User Information

Phone and Verification

Service