Errors

Tots els endpoints de /api/v1/* retornen el mateix sobre d'error. error.code és estable: pots basar-hi la lògica sense dependre del text del missatge.

Els endpoints OAuth2 /oauth/token i /oauth/revoke fan servir errors del protocol (per exemple, {"error":"invalid_grant"} si el codi o el refresh token no és vàlid), en lloc d'aquest sobre de l'API pública. Consulta Autenticació i scopes.

El sobre

{
  "error": {
    "type": "validation_error",
    "code": "invoice.nif_receptor_invalid",
    "message": "El NIF del receptor no té un format vàlid",
    "param": "partner.id_num"
  }
}

Camp	Descripció
type	Categoria general de l'error.
code	Codi estable i llegible per màquina. Basa-hi les decisions.
message	Text orientatiu per depurar. No el processis.
details	Dades estructurades específiques, si n'hi ha.
param	Camp afectat, quan aplica.

Categories

type	HTTP	Significat
validation_error	400	Cos o paràmetres invàlids.
authentication_error	401	Credencial absent, invàlida o caducada.
permission_error	403	Falta un scope o l'operació no està permesa.
not_found_error	404	El recurs no existeix al tenant.
conflict_error	409 / 422	Conflicte amb l'estat actual o amb la idempotència.
billing_error	402	El pla ha arribat a un límit d'ús.
verifactu_error	422	L'AEAT rebutjaria l'operació.
internal_error	500	Error inesperat del servei.

Codis habituals

Autenticació i permisos

code	Quan
api_key.missing	No s'ha enviat Authorization.
api_key.invalid	La clau no existeix o ha estat revocada.
api_key.no_scopes	La clau no té cap scope.
oauth.invalid_token	L'access token OAuth és invàlid, ha caducat o s'ha revocat.
api_key.insufficient_scopes	A la clau li falta l'scope de l'endpoint.
oauth.insufficient_scopes	Al token OAuth li falta l'scope necessari.
mutability.invoice_locked	S'intenta editar una factura que no és un esborrany.
plan_permission_required	El pla no inclou la funcionalitat.

Límit del pla (402)

plan_limit_reached inclou a details la metric, plan_code, limit, used i, per a mètriques mensuals, reset_at. No repeteixis la mateixa operació fins que s'alliberi consum, comenci un altre mes o canviï el pla.

Validació (400)

code	Quan
invalid_body	El JSON no compleix l'esquema.
param.invalid_uuid	Un UUID de la ruta és invàlid.
pagination.invalid_cursor	El cursor no és vàlid.
invoices.partner_required	El tipus de factura exigeix partner_id.
idempotency.key_too_long	Idempotency-Key supera 255 caràcters.

No trobat (404)

Entre altres: invoice.not_found, invoice_line.not_found, partner.not_found, product.not_found, serie.not_found, tax.not_found, economic_activity.not_found, verifactu_record.not_found i external_invoice.not_found.

Conflicte (409)

code	Quan
partner.external_id_taken / product.external_id_taken	L'identificador extern ja està en ús.
partner.id_num_taken / product.name_taken	La identificació o el nom ja existeix.
serie.code_taken	Ja existeix una sèrie amb aquest code.
serie.in_use	La sèrie té documents i no es pot eliminar.
serie.numbering_started	La sèrie ja ha numerat: només poden canviar name i is_active.
serie.type_immutable	El tipus de sèrie no es pot canviar.
serie.last_of_type	No es pot eliminar l'última sèrie d'un tipus.
economic_activity.in_use	L'activitat està referenciada per factures.
economic_activity.last_activity	No es pot eliminar l'última activitat.
idempotency.request_in_progress	Una petició amb la mateixa clau encara s'està processant.
issuance_authorization_required	L'emissió encara no està habilitada.
external_invoices_not_enabled	Verifactu Direct API no està habilitat.

Reutilitzar una Idempotency-Key amb un cos diferent retorna 422 i idempotency.key_reused_with_different_body. Utilitza una clau nova per operació.

VeriFactu / no processable (422)

Amb type: verifactu_error, la forma és vàlida però l'AEAT rebutjaria les dades: desglossament incoherent, factura simplificada per sobre del límit o NIF no identificat. message descriu la causa concreta.

Gestió recomanada

• Basa la lògica en error.code, mai en message.
• En 401 o 403, revisa la clau i els scopes; no repeteixis la mateixa petició.
• En 409, torna a llegir l'estat del servidor i reconcilia'l.
• En 422 durant l'emissió, la factura continua en esborrany: corregeix-la i torna-ho a provar.
• idempotency.request_in_progress es pot reintentar al cap d'uns segons; idempotency.key_reused_with_different_body exigeix una clau nova.