Error codes and the error envelope

1. Every 4xx and 5xx returns { "error": { type, code, message, param?, doc_url, request_id, errors? } }.
2. Branch on type to decide whether a retry makes sense, and map code into your own system.
3. param points at the offending field, e.g. lines.0.vat_rate; errors[] appears when there are several.
4. Log request_id on every error — it lets us find the exact request in our logs.

json
{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "Datele trimise nu sunt valide.",
    "param": "lines.0.vat_rate",
    "doc_url": "https://4invoices.net/ro/api-dezvoltatori#errors",
    "request_id": "req_8a893f2f33d4472da8d6e144",
    "errors": [
      { "param": "lines.0.vat_rate", "message": "VAT rate must be a percent (21), not a fraction", "type": "value_error" }
    ]
  }
}

https://api.4invoices.net/v1 · https://api.4invoices.net/v1/openapi.json

• rate_limit_error and the two upstream types are retryable. authentication_error, permission_error and invalid_request_error are not fixed by retrying.
• A 404 is also returned for an id that belongs to another tenant: we never confirm that someone else's data exists.
• 409 idempotency_key_reuse means you reused a key with a different body. Do not force it: check what was already issued.
• The doc_url in every error points straight at the errors section of this documentation.
• Messages are in Romanian because the API serves a Romanian fiscal flow; do not parse message, branch on code.