EXTERNAL_SERVICE

Error communicating with the external service

Category: General


HTTP status	`502` Bad Gateway
Retry	Yes, unchanged

When it happens

The AEAT census could not be reached to validate the NIF, so the account or company was not created. Nothing was stored.

How to fix it

Repeat the same request later, with the same Idempotency-Key if you sent one. No Retry-After header is sent.

Retry

Retry the same request unchanged, with the same Idempotency-Key if you sent one. Wait first, and honour the Retry-After header when the response carries it.

Returned by

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

POST /v1/accounts/{account_id}/companies

Example response

When this error occurs, the API answers 502 Bad Gateway with a JSON body of this shape:

{
  "type": "https://docs.beel.es/errors/EXTERNAL_SERVICE_ERROR",
  "title": "EXTERNAL_SERVICE_ERROR",
  "detail": "Error communicating with the external service",
  "instance": "/v1/<resource>",
  "errors": [],
  "success": false,
  "error": {
    "code": "EXTERNAL_SERVICE_ERROR",
    "message": "Error communicating with the external service",
    "details": {}
  },
  "meta": {
    "timestamp": "2026-05-21T10:00:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}