Códigos de error y la envoltura de error

1. Todos los 4xx y 5xx devuelven { "error": { type, code, message, param?, doc_url, request_id, errors? } }.
2. Ramifica sobre type para decidir si tiene sentido reintentar, y mapea code en tu propio sistema.
3. param señala el campo erróneo, p. ej. lines.0.vat_rate; errors[] aparece cuando hay varios.
4. Registra request_id en cada error: nos permite encontrar la petición exacta en nuestros 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 y los dos tipos upstream se pueden reintentar. authentication_error, permission_error e invalid_request_error no se resuelven reintentando.
• También se devuelve un 404 para un id que pertenece a otro tenant: nunca confirmamos que existan datos de otra persona.
• 409 idempotency_key_reuse significa que has reutilizado una clave con un cuerpo distinto. No lo fuerces: comprueba qué se emitió ya.
• El doc_url de cada error apunta directamente a la sección de errores de esta documentación.
• Los mensajes están en rumano porque la API atiende un flujo fiscal rumano; no analices message, ramifica sobre code.