Errores y recuperación

Utiliza códigos de error estables para decidir si debes corregir, esperar o reintentar.

Qué hacer

Basa la lógica en el estado HTTP y error.code, no en el texto de error.message.
Un 401 requiere autenticación válida; un 403, cambios de acceso o plan; un 409, comprobar la operación en conflicto o la versión del recurso.

Acceso denegado y reintentos

401: 401 no siempre significa que el token haya caducado. Si ha caducado, obtén otro y repite la lectura como máximo una vez. Si la obtención del token devuelve 401, comprueba la clave y detén los intentos automáticos.
403: Ante un 403, comprueba los permisos, las restricciones IP y el plan. Un token nuevo no restablece un acceso revocado.

Autenticación

Política de reintentos

Limita los reintentos de fallos transitorios y aplica esperas progresivas con una variación aleatoria.
Respeta Retry-After cuando se incluya.
Si una escritura agota el tiempo de espera, su resultado puede ser desconocido: conserva el mismo Idempotency-Key y la solicitud sin cambios al repetir esa operación lógica.
El catálogo siguiente explica todos los códigos de error publicados.

Escrituras seguras

Límites de solicitudes

422 / 409

Para los precios, un formato de moneda o una precisión del importe no válidos devuelven 422 request.validation_failed.
Un código de moneda válido que no coincide con la lista de precios seleccionada devuelve 409 resource.version_conflict.
Comprueba el contexto y las versiones antes de reintentar.

Catálogo de errores

400request.malformedNo se puede interpretar la solicitud.

Qué hacer: Comprueba la sintaxis JSON, la codificación de la URL y la estructura de la solicitud.
Política de reintentos: Reintenta después de corregir la solicitud.

JSON

{
  "error": {
    "code": "request.malformed",
    "fields": null,
    "message": "The request could not be read."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.invalid_credentialsLa clave API o el token de acceso no son válidos, han caducado o se han revocado.

Qué hacer: Comprueba la URL de la tienda y la credencial. Obtén un token nuevo con una clave API activa.
Política de reintentos: Reintenta después de corregir la autenticación; evita solicitar repetidamente tokens no válidos.

JSON

{
  "error": {
    "code": "authentication.invalid_credentials",
    "fields": null,
    "message": "The credentials are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.requiredFalta la cabecera Authorization requerida o su esquema es incorrecto.

Qué hacer: Utiliza ApiKey para solicitar un token y Bearer para las operaciones de recursos.
Política de reintentos: Reintenta después de enviar la cabecera correcta.

JSON

{
  "error": {
    "code": "authentication.required",
    "fields": null,
    "message": "Authentication is required."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.client_ip_unverifiedEl servicio no pudo determinar una dirección IP de cliente fiable.

Qué hacer: Pide al operador de la tienda que compruebe la ruta de entrada. No añadas por tu cuenta cabeceras de reenvío.
Política de reintentos: Reintenta cuando se restablezca la conexión de confianza.

JSON

{
  "error": {
    "code": "authorization.client_ip_unverified",
    "fields": null,
    "message": "The client IP address could not be verified."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.ip_not_allowedLa IP de origen no figura en la lista de direcciones permitidas para la clave.

Qué hacer: Utiliza una dirección de origen aprobada o pide a un administrador autorizado que edite la lista IP de la clave.
Política de reintentos: Reintenta solo cuando la dirección esté permitida.

JSON

{
  "error": {
    "code": "authorization.ip_not_allowed",
    "fields": null,
    "message": "Access from this IP address is not allowed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.scope_deniedLa clave carece de un permiso efectivo necesario para esta operación.

Qué hacer: Comprueba los permisos obligatorios y condicionales de la operación, los permisos de la clave y el acceso de quien la emitió.
Política de reintentos: Reintenta cuando un administrador autorizado conceda el acceso necesario.

JSON

{
  "error": {
    "code": "authorization.scope_denied",
    "fields": null,
    "message": "The required permission has not been granted."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.api_disabledEl acceso API está deshabilitado para esta tienda.

Qué hacer: Pide al propietario que compruebe el plan activo y la disponibilidad de la API.
Política de reintentos: No reintentes hasta que se habilite el acceso API.

JSON

{
  "error": {
    "code": "entitlements.api_disabled",
    "fields": null,
    "message": "API access is disabled for this store."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.limit_exceededEl cambio superaría un límite del plan actual.

Qué hacer: Comprueba el límite aplicable al recurso y ajusta el cambio previsto o el plan.
Política de reintentos: Reintenta tras resolver el límite; utiliza otra clave de idempotencia si cambia la solicitud.

JSON

{
  "error": {
    "code": "entitlements.limit_exceeded",
    "fields": null,
    "message": "The operation exceeds a plan limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.operation_disabledEl plan actual no incluye esta operación.

Qué hacer: Comprueba el plan mínimo indicado para la operación.
Política de reintentos: Reintenta cuando el plan admita la operación y la clave tenga los permisos necesarios.

JSON

{
  "error": {
    "code": "entitlements.operation_disabled",
    "fields": null,
    "message": "The current plan does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.resource_blockedUn límite del plan bloquea este recurso concreto.

Qué hacer: Pide al propietario que resuelva la restricción del plan para el recurso.
Política de reintentos: No repitas la misma solicitud mientras el recurso siga bloqueado.

JSON

{
  "error": {
    "code": "entitlements.resource_blocked",
    "fields": null,
    "message": "A plan limit blocks access to this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

404resource.not_foundEl recurso no existe, se eliminó o no está disponible con el identificador enviado.

Qué hacer: Comprueba la tienda, la ruta y el identificador del recurso. Utiliza identificadores devueltos por esta tienda.
Política de reintentos: Reintenta solo después de corregir el destino o confirmar su existencia.

JSON

{
  "error": {
    "code": "resource.not_found",
    "fields": null,
    "message": "The resource was not found."
  },
  "meta": {
    "request_id": "example-request"
  }
}

405request.method_not_allowedEl endpoint no admite este método HTTP.

Qué hacer: Utiliza el método documentado; la cabecera Allow indica los métodos admitidos.
Política de reintentos: No reintentes con el método no admitido.

JSON

{
  "error": {
    "code": "request.method_not_allowed",
    "fields": null,
    "message": "This method is not supported for this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409idempotency.key_reusedEsta clave de idempotencia pertenece a otra solicitud.

Qué hacer: Localiza la operación original. Utiliza una clave nueva solo para una operación lógica nueva e intencionada.
Política de reintentos: No reintentes con un contenido modificado y la clave en conflicto.

JSON

{
  "error": {
    "code": "idempotency.key_reused",
    "fields": null,
    "message": "This idempotency key was used with a different request."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.already_existsUn valor único entra en conflicto con un recurso existente.

Qué hacer: Lee el recurso existente y decide si debes utilizarlo o elegir otro valor único.
Política de reintentos: No repitas la misma creación en conflicto.

JSON

{
  "error": {
    "code": "resource.already_exists",
    "fields": null,
    "message": "A resource with these unique values already exists."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.in_useOtros recursos todavía dependen de este recurso.

Qué hacer: Revisa las dependencias y elimínalas o modifícalas mediante operaciones admitidas antes de eliminarlo.
Política de reintentos: Reintenta después de resolver las dependencias.

JSON

{
  "error": {
    "code": "resource.in_use",
    "fields": null,
    "message": "The resource is still in use."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.state_conflictEl estado de negocio actual impide este cambio.

Qué hacer: Lee el estado actual y elige una transición de negocio válida.
Política de reintentos: No fuerces automáticamente el cambio ni lo envíes repetidamente mientras exista el conflicto.

JSON

{
  "error": {
    "code": "resource.state_conflict",
    "fields": null,
    "message": "The current resource state does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.version_conflictOtra escritura modificó el recurso después de la versión que leíste.

Qué hacer: Lee el estado más reciente, concilia el cambio y envía el nuevo expected_version.
Política de reintentos: Utiliza una nueva clave de idempotencia para la operación revisada; no sobrescribas a ciegas.

JSON

{
  "error": {
    "code": "resource.version_conflict",
    "fields": null,
    "message": "The resource version has changed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

413request.too_largeLa solicitud supera el límite de tamaño.

Qué hacer: Reduce el contenido o divide el trabajo en operaciones individuales admitidas.
Política de reintentos: Reintenta con operaciones válidas más pequeñas y sus propias claves de idempotencia.

JSON

{
  "error": {
    "code": "request.too_large",
    "fields": null,
    "message": "The request exceeds the size limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

415request.unsupported_media_typeEl tipo de contenido o su codificación no están admitidos.

Qué hacer: En escrituras JSON utiliza Content-Type: application/json y un cuerpo sin compresión admitido.
Política de reintentos: Reintenta después de corregir el tipo o la codificación del contenido.

JSON

{
  "error": {
    "code": "request.unsupported_media_type",
    "fields": null,
    "message": "The request media type or encoding is not supported."
  },
  "meta": {
    "request_id": "example-request"
  }
}

422request.validation_failedUno o varios campos o parámetros no superan la validación.

Qué hacer: Consulta error.fields y comprueba los campos obligatorios, la admisión de null, los identificadores y los valores permitidos.
Política de reintentos: Reintenta con una solicitud corregida; una escritura modificada es una operación lógica nueva.

JSON

{
  "error": {
    "code": "request.validation_failed",
    "fields": null,
    "message": "Some request parameters are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.queue_fullLa cola breve de la API está llena; la solicitud no ha comenzado a ejecutarse.

Qué hacer: Pon las solicitudes en cola y respeta la cabecera de respuesta Retry-After.
Política de reintentos: Espera al menos los segundos indicados por Retry-After y añade una variación aleatoria. Conserva la clave y el contenido originales al reintentar una escritura.

JSON

{
  "error": {
    "code": "capacity.queue_full",
    "fields": null,
    "message": "The API is busy. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.wait_timeoutHa vencido el tiempo de espera en la cola de la API; la solicitud no ha comenzado a ejecutarse.

Qué hacer: Pon las solicitudes en cola y respeta la cabecera de respuesta Retry-After.
Política de reintentos: Espera al menos los segundos indicados por Retry-After y añade una variación aleatoria. Conserva la clave y el contenido originales al reintentar una escritura.

JSON

{
  "error": {
    "code": "capacity.wait_timeout",
    "fields": null,
    "message": "The API could not start this request in time. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429rate_limit.exceededLa frecuencia de solicitudes supera el límite aplicable.

Qué hacer: Pon las solicitudes en cola y respeta la cabecera de respuesta Retry-After.
Política de reintentos: Espera al menos los segundos indicados por Retry-After y añade una variación aleatoria. Conserva la clave y el contenido originales al reintentar una escritura.

JSON

{
  "error": {
    "code": "rate_limit.exceeded",
    "fields": null,
    "message": "The request rate limit has been exceeded."
  },
  "meta": {
    "request_id": "example-request"
  }
}

500internal.errorSe produjo un error inesperado del servicio.

Qué hacer: Registra el identificador de solicitud y contacta con el operador si persiste; excluye las credenciales de los registros.
Política de reintentos: Limita los reintentos y aumenta la espera. En escrituras conserva la clave de idempotencia original y el contenido sin cambios.

JSON

{
  "error": {
    "code": "internal.error",
    "fields": null,
    "message": "An unexpected error occurred."
  },
  "meta": {
    "request_id": "example-request"
  }
}

502gateway.bad_responseLa pasarela no recibió una respuesta API válida.

Qué hacer: Conserva el identificador de solicitud. Una respuesta fallida no demuestra que la escritura no se haya aplicado.
Política de reintentos: Limita los reintentos y aumenta la espera; repite la misma escritura lógica con su Idempotency-Key y contenido originales.

JSON

{
  "error": {
    "code": "gateway.bad_response",
    "fields": null,
    "message": "The API gateway could not obtain a valid response."
  },
  "meta": {
    "request_id": "example-request"
  }
}

503service.unavailableLa API no puede atender la solicitud temporalmente.

Qué hacer: Respeta Retry-After cuando se incluya y conserva el identificador de solicitud si persiste la incidencia.
Política de reintentos: Limita los reintentos con esperas progresivas y variación aleatoria; conserva la clave y el contenido al repetir la misma escritura.

JSON

{
  "error": {
    "code": "service.unavailable",
    "fields": null,
    "message": "The API is temporarily unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

504gateway.timeoutLa pasarela agotó el tiempo de espera de la API.

Qué hacer: Conserva el identificador de solicitud y considera desconocido el resultado de la escritura.
Política de reintentos: Limita los reintentos y aumenta la espera; en escrituras reutiliza la clave de idempotencia original y el contenido sin cambios.

JSON

{
  "error": {
    "code": "gateway.timeout",
    "fields": null,
    "message": "The API gateway timed out."
  },
  "meta": {
    "request_id": "example-request"
  }
}