Guides

Errors

All errors return the same JSON format, including validation, authentication, not-found, upstream and unknown-path errors.

Code
{
  "error": "The request does not match the published schema",
  "code": "invalid_request"
}

Field	Description
`code`	Stable error code. Branch on this field.
`error`	Human-readable message for logs. May change.

Each operation in the reference lists its codes. New codes may be added. Existing codes are never removed or redefined. Handle unknown codes with a default branch.

Common Codes

Any operation can return these codes.

Code	Status	Description
`invalid_request`	400	Body or path does not match the schema.
`unreadable_request`	400	Body does not match its declared media type.
`unauthorized`	401	Key missing, malformed or revoked.
`payload_too_large`	413	Body exceeds the size limit.
`upstream_failed`	502	Failure at Lunch or an upstream provider.
`unknown_endpoint`	404	Path not supported.

unknown_endpoint is not listed under any operation. It is returned as JSON, not plain text.

Codes to Handle by Name

Code	Description
`business_not_found`, `invoice_not_found`, `import_not_found`, `subscription_not_found`	Usually an identifier that has not been synced.
`invoice_not_financeable`	`409`. The invoice is not eligible for an advance. See Requesting an Advance.
`business_not_eligible`	`409`. Onboarding is incomplete. See Requesting an Advance.
`concentration_exceeded`	`409`. The vendor's limit would be exceeded. See Requesting an Advance.
`already_subscribed`	The endpoint is already subscribed.
`already_imported`	The import identifier was already used for a different file.
`invalid_routing_number`	Invalid routing number.
`invalid_invitee`	Invalid invitee.
`self_dealing`	An organization attempted to take an advance on its own invoice.
`unsupported_media_type`, `unreadable_file`	Invoice import errors.
`too_many_rows`	Import exceeds 1000 rows.
`destination_refused`	Webhook URL not allowed.

Retrying

Retry 502 with backoff. 4xx errors repeat until the request or the underlying state changes. For timeouts, see Idempotent Requests.

What's Next

Webhooks

Last modified on September 23, 2026

Webhooks