Mã lỗi và khung lỗi

1. Mọi lỗi 4xx và 5xx đều trả về { "error": { type, code, message, param?, doc_url, request_id, errors? } }.
2. Rẽ nhánh theo type để quyết định có nên thử lại không, và ánh xạ code vào hệ thống của bạn.
3. param trỏ đến trường gây lỗi, ví dụ lines.0.vat_rate; errors[] xuất hiện khi có nhiều lỗi.
4. Ghi lại request_id trong mọi lỗi — nhờ đó chúng tôi tìm được đúng yêu cầu trong nhật ký.

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 và hai loại upstream có thể thử lại. authentication_error, permission_error và invalid_request_error không được khắc phục bằng cách thử lại.
• 404 cũng được trả về cho một id thuộc về tenant khác: chúng tôi không bao giờ xác nhận rằng dữ liệu của người khác tồn tại.
• 409 idempotency_key_reuse nghĩa là bạn đã dùng lại khóa với nội dung khác. Đừng ép buộc: hãy kiểm tra những gì đã được phát hành.
• doc_url trong mọi lỗi trỏ thẳng đến phần lỗi của tài liệu này.
• Thông báo lỗi bằng tiếng Romania vì API phục vụ luồng hóa đơn tài chính của Romania; đừng phân tích message, hãy rẽ nhánh theo code.