Codes d'erreur et enveloppe d'erreur

1. Toutes les réponses 4xx et 5xx renvoient { "error": { type, code, message, param?, doc_url, request_id, errors? } }.
2. Branchez votre logique sur type pour décider si une nouvelle tentative a du sens, et faites correspondre code dans votre propre système.
3. param désigne le champ en cause, par ex. lines.0.vat_rate ; errors[] apparaît lorsqu’il y en a plusieurs.
4. Journalisez request_id pour chaque erreur — cela nous permet de retrouver la requête exacte dans nos 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 et les deux types upstream peuvent être relancés. authentication_error, permission_error et invalid_request_error ne se résolvent pas en réessayant.
• Un 404 est également renvoyé pour un id appartenant à un autre tenant : nous ne confirmons jamais l’existence des données de quelqu’un d’autre.
• 409 idempotency_key_reuse signifie que vous avez réutilisé une clé avec un corps différent. Ne forcez pas : vérifiez ce qui a déjà été émis.
• La doc_url de chaque erreur renvoie directement à la section des erreurs de cette documentation.
• Les messages sont en roumain parce que l’API sert un processus fiscal roumain ; n’analysez pas message, branchez votre logique sur code.