NIF_NOT_IN_CENSUS

When it happens

The tax authority's census has no taxpayer with that NIF, or the name registered for it does not match the fiscal name you sent. Typos in either the NIF or the legal name are the usual cause.

How to fix it

Check the NIF and the exact legal name with your customer. You can test the pair with POST /v1/nif/validate before creating the customer or the invoice.

Retry

Not as is: the same request fails the same way. Fix the cause described above, then send the request again, under a new Idempotency-Key if the body changed.

Returned by

The operations where this code is most likely. The list is not exhaustive.

• POST /v1/companies/{company_id}/customers
• POST /v1/companies/{company_id}/invoices
• PATCH /v1/companies/{company_id}/invoices/{invoice_id}
• POST /v1/companies/{company_id}/invoices/{invoice_id}/issue

Rules that cite this code

• CNT-020 A Spanish recipient's NIF is in the AEAT census

Example response

When this error occurs, the API answers 422 Unprocessable Content with a JSON body of this shape:

{
  "type": "https://docs.beel.es/errors/NIF_NOT_IN_CENSUS",
  "title": "NIF_NOT_IN_CENSUS",
  "detail": "The NIF '‹nif›' does not exist in the AEAT census or the fiscal name does not match",
  "instance": "/v1/<resource>",
  "errors": [],
  "success": false,
  "error": {
    "code": "NIF_NOT_IN_CENSUS",
    "message": "The NIF '‹nif›' does not exist in the AEAT census or the fiscal name does not match",
    "details": {}
  },
  "meta": {
    "timestamp": "2026-05-21T10:00:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

The type URI is stable and always resolves to this page.

Message

Send the request with Accept-Language: <es|en|ca> to receive the message in your preferred language.

Placeholders are filled in at runtime:

• ‹nif› — the NIF that was checked.

Other errors in this category

Keep exploring