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.

Error shape
{
  "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."
}

cURL · Request without a credential
curl "$CLOBEPAY_API_BASE/me"

Expected response: HTTP 401

What to do with each code

HTTP codes and recommended action
HTTPMeaningAction
400Invalid request (validation, missing Idempotency-Key, ambiguous credentials)Fix the request. Do not retry as is.
401Credential missing, invalid, revoked, expired or from another environmentCheck the key. Do not retry.
403Missing scope or merchant not operationalCheck permissions or the merchant status.
404Not found or belongs to another merchantCheck the identifier.
409State conflict (verification not approved, idempotent request in progress)Fix the state; if it is idempotency_request_in_progress, retry.
422Business rule (amount, reused Idempotency-Key, URL not allowed)Fix the body.
429Rate limitWait for Retry-After and retry.
5xxTransient errorRetry 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.