Errors

Errors use HTTP status codes and an RFC 9457 application/problem+json body:

{
  "type": "https://invoice.horizonpay.co/problems/invalid-state",
  "title": "Invalid state for this operation",
  "status": 409,
  "detail": "This invoice has been finalized and can no longer be edited.",
  "instance": "req_4f0c2a9e8b7d4c1fa3e2b6d9c0e1f2a3",
  "code": "invalid_state"
}

Branch on code. The wording of detail can change.
instance is the request id, also sent as the X-Request-Id header. Include it when you contact support. You can send your own X-Request-Id (up to 200 characters) and it’s echoed back.
errors appears on 422 responses: a list of { "path", "message" }, such as { "path": "items.0.unit_amount", "message": "Use whole minor units" }.

Error codes

`code`	Status	Retry?	Meaning
`validation`	`422`	No	A field or query parameter is invalid. See `errors`.
`idempotency_mismatch`	`422`	No	An `Idempotency-Key` was reused with a different request.
`unauthorized`	`401`	No	The API key is missing, invalid, revoked or expired.
`forbidden`	`403`	No	The key lacks the scope this endpoint needs.
`not_found`	`404`	No	No such resource, or the id is malformed.
`invalid_state`	`409`	No	The resource is in the wrong state, such as editing a finalized invoice.
`conflict`	`409`	Yes	A request with the same `Idempotency-Key` is still running, or a write clashed with another one.
`idempotency_key_required`	`428`	No	This endpoint needs an `Idempotency-Key` header.
`rate_limited`	`429`	After `Retry-After`	You hit a rate limit.
`internal_error`	`500`	Yes	Something went wrong on our side.
`upstream_failed`	`502`	Yes	A service we depend on failed: the email provider or the database.

Also retry network errors and timeouts. When you retry a write, reuse the same Idempotency-Key. The SDKs retry for you.

A 502 from POST /invoices/{id}/send can arrive after the invoice was finalized. The invoice keeps its number, and an invoice.email_failed event is recorded. Retry the send.

Get started

Basics

Webhooks

Error codes

​Error codes

Error codes