IDEMPOTENCY_KEY_REQUIRED
This operation requires the Idempotency-Key header: without it, a retry would import the same file twice.
Category: General
| HTTP status | 400 Bad Request |
| Retry | After fixing the cause |
When it happens
The operation requires the Idempotency-Key header and the request did not send it. It is mandatory where a repeated call would duplicate data, such as imports.
How to fix it
Send an Idempotency-Key header with a unique value for the operation.
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.
Example response
When this error occurs, the API answers 400 Bad Request with a JSON body of this shape:
{
"type": "https://docs.beel.es/errors/IDEMPOTENCY_KEY_REQUIRED",
"title": "IDEMPOTENCY_KEY_REQUIRED",
"detail": "This operation requires the Idempotency-Key header: without it, a retry would import the same file twice.",
"instance": "/v1/<resource>",
"errors": [],
"success": false,
"error": {
"code": "IDEMPOTENCY_KEY_REQUIRED",
"message": "This operation requires the Idempotency-Key header: without it, a retry would import the same file twice.",
"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.
Other errors in this category
AUTOMATIC_EMAIL_CONFIG_INVALID
For automatic sending, you must provide an email configuration or a client with email
BAD_REQUEST
The provided data is not valid.
BUSINESS_RULE_VIOLATION
The operation breaks a business rule.
CITY_EMPTY
City cannot be empty
CITY_MAX_LENGTH
City cannot exceed ‹value› characters