Errors
Error response shape, stable codes and what to retry.
Every error response is JSON with a stable code in error, a readable message in message, the time in timestamp and the route in path. Code against error, never against the message text.
{
"statusCode": 401,
"timestamp": "2026-11-19T18:00:00.000Z",
"path": "/api/v1/me",
"error": "invalid_api_key",
"message": "La llave de API no es válida."
}An undeclared field or a field with an invalid type returns the standard validation 400:
error is Bad Request and message is an array with one text per field.curl "$CLOBEPAY_API_BASE/me"Expected response: HTTP 401
What to do with each code
| HTTP | Meaning | Action |
|---|---|---|
| 400 | Invalid request (validation, missing Idempotency-Key, ambiguous credentials) | Fix the request. Do not retry as is. |
| 401 | Credential missing, invalid, revoked, expired or from another environment | Check the key. Do not retry. |
| 403 | Missing scope or merchant not operational | Check permissions or the merchant status. |
| 404 | Not found or belongs to another merchant | Check the identifier. |
| 409 | State conflict (verification not approved, idempotent request in progress) | Fix the state; if it is idempotency_request_in_progress, retry. |
| 422 | Business rule (amount, reused Idempotency-Key, URL not allowed) | Fix the body. |
| 429 | Rate limit | Wait for Retry-After and retry. |
| 5xx | Transient error | Retry with backoff and the same Idempotency-Key. |
Timeouts and network errors
The outcome is uncertain: do not create another operation. Retry with the same Idempotency-Key or query the resource. Log error, path and timestamp, without personal data or secrets.