# Errors

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

```json
{
  "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](/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](/financing-an-invoice). |
| `business_not_eligible` | `409`. Onboarding is incomplete. See [Requesting an Advance](/financing-an-invoice). |
| `concentration_exceeded` | `409`. The vendor's limit would be exceeded. See [Requesting an Advance](/financing-an-invoice). |
| `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](/idempotent-requests).

## What's Next

- [Webhooks](/webhooks)