Erros & Status
Entenda as respostas de erro da API e como tratar excepções na sua integração.
Formato de Erro
Todos os erros seguem uma estrutura previsível, facilitando o tratamento programático.
400 Bad Request
{
"error": "validation_error",
"issues": [
{ "code": "invalid_type", "path": ["taxId"], "message": "Expected string, received number" }
]
}A maioria dos erros é apenas { error: "codigo" } - sem issues. Esse campo só aparece em erros de validação (400).
Códigos HTTP
| Código | Status | Significado |
|---|---|---|
| 400 | Bad Request | O pedido é inválido ou faltam parâmetros obrigatórios. |
| 401 | Unauthorized | Chave de API inválida ou expirada. |
| 402 | Payment Required | Plano expirado ou limite do plano gratuito atingido (plan_expired / plan_limit_reached). |
| 403 | Forbidden | Não tem permissão para aceder ao recurso solicitado (ou a empresa ainda não autorizou o Box - box_consent_pending). |
| 404 | Not Found | O recurso (factura, cliente, etc.) não foi encontrado. |
| 422 | Unprocessable | Dados semanticamente inválidos (ex: NIF mal formatado). |
| 429 | Too Many Requests | Limite de pedidos por minuto excedido. |
| 500 | Server Error | Erro interno - contacte o suporte se persistir. |
Tratar Erros no SDK
Os SDKs expõem erros tipados para cada categoria:
TypeScript
import { VeroError, VeroAPIError, VeroAuthError } from '@veroao/node'
try {
const invoice = await vero.invoices.create('org_123', input)
} catch (err) {
if (err instanceof VeroAuthError) {
// 401 - chave inválida
} else if (err instanceof VeroAPIError) {
// 4xx / 5xx - err.status, err.code, err.message
} else if (err instanceof VeroError) {
// timeout, rede, etc.
}
}