Errors

The Invoice AI API signals errors through standard HTTP status codes combined with a structured error body. Every error response uses the application/problem+json content type, defined by RFC 7807.

Error Response Format

An error response body always contains these four fields:

string

required

A URI that uniquely identifies the error type. Stable across API versions — safe to branch your error-handling code on. Points to documentation for that specific error when fetched.

string

required

A short, human-readable summary of the error type. Does not change between occurrences of the same error. Use type for programmatic checks; use title for display.

integer

required

The HTTP status code for this occurrence. Matches the response’s HTTP status line exactly.

string

required

A human-readable explanation specific to this occurrence of the error. May include the ID of the affected resource or a description of what failed validation. Suitable for displaying to an operator; not guaranteed to be stable across releases.

Example

{
  "type": "https://invoice.horizonpay.co/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Invoice in_xxx was not found"
}

Error responses are not wrapped in a data envelope. Only successful responses use { "data": ... }. Check the HTTP status code first; if it is 4xx or 5xx, parse the body as application/problem+json.

HTTP Status Codes

400 — Bad Request

The request body failed schema validation. The detail field describes which field was invalid. Fix the request body before retrying.

{
  "type": "https://invoice.horizonpay.co/errors/validation",
  "title": "Bad Request",
  "status": 400,
  "detail": "\"amount\" must be a positive integer"
}

401 — Unauthorized

The Authorization header is missing, malformed, or contains a key that does not exist or has been revoked. See the Authentication reference.

{
  "type": "https://invoice.horizonpay.co/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "No valid API key was provided."
}

403 — Forbidden

The API key is valid but does not have the scope required by this endpoint. Add the missing scope to the key or create a new key. See Scopes.

{
  "type": "https://invoice.horizonpay.co/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "This API key does not have the invoices:write scope."
}

A request for a resource that belongs to a different workspace returns 404 Not Found, not 403 Forbidden. Returning 403 would confirm the resource exists, enabling enumeration of other workspaces’ IDs.

404 — Not Found

The requested resource does not exist, has been deleted, or belongs to another workspace.

{
  "type": "https://invoice.horizonpay.co/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Invoice in_xxx was not found"
}

409 — Conflict

A uniqueness or concurrency constraint was violated. The most common cause is retrying a request with the same Idempotency-Key but a different request body. Resolve the conflict before retrying: either use a new Idempotency-Key for a genuinely new request, or resend the original body to safely replay the original request.

{
  "type": "https://invoice.horizonpay.co/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "An idempotency key was reused with a different request body."
}

422 — Unprocessable Entity

The request was syntactically valid and well-formed, but the operation cannot be performed because the resource is in the wrong state. Common examples:

Attempting to finalize an invoice that is already open or paid.
Attempting to void an invoice that has already been voided.
Attempting to add a line item to an invoice that is no longer a draft.

{
  "type": "https://invoice.horizonpay.co/errors/invalid-state",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "This invoice has already been finalized and cannot be edited."
}

Before calling finalize or pay, fetch the invoice and check its status field. Only draft invoices can be finalized; only open invoices can be paid. This avoids most 422 errors without a round-trip to discover them.

429 — Too Many Requests

Your API key has exceeded the rate limit. Back off and retry after the interval indicated in the Retry-After response header (in seconds).

{
  "type": "https://invoice.horizonpay.co/errors/rate-limited",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Retry after 10 seconds."
}

500 — Internal Server Error

An unexpected error occurred on the Invoice AI servers. These are rare. If you receive persistent 500 errors, check the status page and contact support.

{
  "type": "https://invoice.horizonpay.co/errors/internal",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred. Please try again later."
}

Error Type Reference

The type URI carries a machine-stable slug. Use these slugs in your error-handling logic — never branch on the title string, which may be rephrased over time.

`type` slug	HTTP status	Meaning
`validation`	400	Request body failed schema validation
`unauthorized`	401	Missing or invalid API key
`forbidden`	403	Key lacks the required scope
`not-found`	404	Resource does not exist or is not accessible
`conflict`	409	Idempotency key reuse or uniqueness violation
`invalid-state`	422	Resource is in the wrong state for this operation
`rate-limited`	429	Rate limit exceeded
`internal`	500	Unexpected server-side error

Handling Errors

Check the content type

Before parsing an error body, verify the response Content-Type is application/problem+json. Proxies and CDN edge nodes occasionally return their own HTML error pages for network-level errors.

async function apiRequest(url, options) {
  const res = await fetch(url, options);

  if (!res.ok) {
    const contentType = res.headers.get('content-type') ?? '';
    if (contentType.includes('application/problem+json')) {
      const problem = await res.json();
      throw new ApiError(problem);
    }
    // Unexpected non-JSON error (e.g. a proxy's HTML error page)
    throw new Error(`HTTP ${res.status}: ${res.statusText}`);
  }

  return res.json();
}

Retry strategy

Not all errors are worth retrying. Use the following guidance:

Status	Retry?	Notes
400	❌ No	Fix the request body first
401	❌ No	Check and rotate your API key
403	❌ No	Add the required scope to the key
404	❌ No	The resource does not exist
409	❌ No	Resolve the conflict; do not blindly retry
422	❌ No	Fetch the resource and check its current state
429	✅ Yes	Respect the `Retry-After` header
500	✅ Yes	Use exponential backoff with jitter

async function withRetry(fn, maxAttempts = 4) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const retryable = err.status === 429 || err.status >= 500;
      if (!retryable || attempt === maxAttempts) throw err;

      const retryAfter = err.retryAfter ?? Math.pow(2, attempt) * 500;
      await new Promise(resolve => setTimeout(resolve, retryAfter));
    }
  }
}

Never implement a blind retry loop for 409 Conflict. A conflict caused by an idempotency key mismatch will not resolve itself — retrying only produces more 409 responses.

Overview

Invoices

Customers & Catalog

Webhooks

Invoice AI API Errors: Status Codes & Problem+JSON

Errors

Error Response Format

Example

HTTP Status Codes

400 — Bad Request

401 — Unauthorized

403 — Forbidden

404 — Not Found

409 — Conflict

422 — Unprocessable Entity

429 — Too Many Requests

500 — Internal Server Error

Error Type Reference

Handling Errors

Check the content type

Retry strategy

​Errors

​Error Response Format

​Example

​HTTP Status Codes

​400 — Bad Request

​401 — Unauthorized

​403 — Forbidden

​404 — Not Found

​409 — Conflict

​422 — Unprocessable Entity

​429 — Too Many Requests

​500 — Internal Server Error

​Error Type Reference

​Handling Errors

​Check the content type

​Retry strategy

Errors

Error Response Format

Example

HTTP Status Codes

400 — Bad Request

401 — Unauthorized

403 — Forbidden

404 — Not Found

409 — Conflict

422 — Unprocessable Entity

429 — Too Many Requests

500 — Internal Server Error

Error Type Reference

Handling Errors

Check the content type

Retry strategy