Error handling — FiscalRail documentation

FiscalRail uses standard HTTP response codes. 2xx responses indicate success, 4xx responses indicate a problem with the request or account, and 5xx responses indicate an error on our side.

A 5xx response does not necessarily mean that the operation had no effect. Record the response's Request-Id header before retrying or contacting support so we can trace the request.

Error responses

API errors are returned as JSON under a top-level error property:

{
  "error": {
    "code": "invalid_request",
    "message": "limit must be between 1 and 100"
  }
}

Every error includes a stable machine-readable code and a human-readable message. Validation errors may also include a details array identifying individual fields and violations. Integrations should branch on the HTTP status and code, not the text of message.

Validation details use dotted field paths where necessary:

{
  "error": {
    "code": "invalid_customer",
    "message": "The customer is invalid",
    "details": [
      {
        "code": "required_value",
        "field": "tax_id.country",
        "message": "can't be blank",
        "metadata": {}
      }
    ]
  }
}

Common errors

HTTP status	Code	Meaning
`400`	`invalid_request`	The request could not be parsed or contains an invalid parameter.
`401`	`authentication_required`	The API key is missing, malformed or unknown.
`402`	`balance_exhausted`	The live account does not have enough balance for a billable operation.
`404`	`resource_not_found`	The resource does not exist or belongs to another account.
`409`	`idempotency_key_in_use`	Another request is currently using the same idempotency key.
`409`	`idempotency_key_mismatch`	The idempotency key was reused for another operation or different parameters.

Resource and operation errors

These codes apply only when the corresponding resource or operation is involved:

HTTP status	Code	Meaning
`404`	`customer_not_found`	The customer supplied when issuing an invoice does not exist in the account.
`409`	`pdf_render_in_progress`	Another request is already rendering the invoice PDF. Retry after a short delay.
`422`	`invalid_customer`	Customer data is invalid, or the requested customer operation is not allowed. Check `details`.
`422`	`invalid_invoice`	Invoice data is invalid. Check `details`.
`422`	`account_not_configured`	The account is missing configuration required by the operation.
`503`	`pdf_rendering_unavailable`	PDF rendering is temporarily unavailable. Retry later.

Safe retries

Retry transient 5xx responses with exponential backoff and jitter. Do not retry 4xx responses without changing the request or account state.

For operations that support idempotency, reuse the same Idempotency-Key when retrying an inconclusive request. See Idempotency.