Códigos de erro e o envelope de erro

1. Todos os 4xx e 5xx devolvem { "error": { type, code, message, param?, doc_url, request_id, errors? } }.
2. Decida o fluxo com base em type para saber se faz sentido tentar de novo, e mapeie code no seu próprio sistema.
3. param aponta para o campo em causa, p. ex. lines.0.vat_rate; errors[] aparece quando há vários.
4. Registe request_id em cada erro — permite-nos encontrar o pedido exato nos nossos 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 e os dois tipos upstream podem ser repetidos. authentication_error, permission_error e invalid_request_error não se resolvem com novas tentativas.
• Também é devolvido um 404 para um id que pertence a outro tenant: nunca confirmamos a existência de dados de terceiros.
• 409 idempotency_key_reuse significa que reutilizou uma chave com um corpo diferente. Não force: verifique o que já foi emitido.
• O doc_url de cada erro aponta diretamente para a secção de erros desta documentação.
• As mensagens estão em romeno porque a API serve um fluxo fiscal romeno; não faça parsing de message, decida com base em code.