Кодове за грешки и форматът на грешката

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.