Коди помилок і конверт помилки

1. Кожна 4xx і 5xx повертає { "error": { type, code, message, param?, doc_url, request_id, помилки? } }.
2. Розгалужуйте логіку за type, щоб вирішити, чи має сенс повторна спроба, і зіставляйте code у своїй системі.
3. param вказує на проблемне поле, наприклад lines.0.vat_rate; помилки[] з’являється, коли таких полів кілька.
4. Записуйте request_id під час кожної помилки — це дає нам змогу знайти точний запит у наших журналах.

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 і два типи апстрім допускають повторну спробу. authentication_error, permission_error і invalid_request_error повторною спробою не виправляються.
• 404 також повертається для id, що належить іншому tenant: ми ніколи не підтверджуємо, що чужі дані існують.
• 409 idempotency_key_reuse означає, що ви повторно використали ключ з іншим тілом. Не обходьте це: перевірте, що вже було випущено.
• doc_url у кожній помилці веде безпосередньо до розділу про помилки в цій документації.
• Повідомлення румунською, бо API обслуговує румунський фіскальний процес; не парсьте message, розгалужуйте логіку за code.