Códigos de error

Si una solicitud falla, comprueba el código de error de la respuesta. Despliégalo en la lista para saber qué ha ocurrido y qué hacer. Cada error incluye un ejemplo de respuesta e indicaciones para volver a enviar la solicitud.

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.

Respuesta

{
  "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.

Respuesta

{
  "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: Para crear o anular un token, usa tu clave de API con ApiKey en la cabecera Authorization. Para las demás solicitudes, usa el token de acceso con Bearer.
Política de reintentos: Reintenta después de enviar la cabecera correcta.

Respuesta

{
  "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: Comprueba desde qué dirección IP se conecta tu integración a la API. Si el error persiste, contacta con el soporte técnico de Shopently.
Política de reintentos: Vuelve a intentarlo cuando se haya resuelto el problema de identificación de la dirección IP.

Respuesta

{
  "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.

Respuesta

{
  "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.

Respuesta

{
  "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.

Respuesta

{
  "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.

Respuesta

{
  "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.

Respuesta

{
  "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.

Respuesta

{
  "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.

Respuesta

{
  "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.

Respuesta

{
  "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.

Respuesta

{
  "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.

Respuesta

{
  "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.

Respuesta

{
  "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.

Respuesta

{
  "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.

Respuesta

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

409storage.limit_reachedSe ha alcanzado el límite de almacenamiento de imágenes y archivos. Libera espacio o aumenta el límite.

Qué hacer: Se ha alcanzado el límite de almacenamiento de imágenes y archivos. Libera espacio o aumenta el límite.
Política de reintentos: Reintenta con operaciones válidas más pequeñas y sus propias claves de idempotencia.

Respuesta

{
  "error": {
    "code": "storage.limit_reached",
    "fields": null,
    "message": "The upload storage limit is reached."
  },
  "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.

Respuesta

{
  "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.

Respuesta

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

416request.range_not_satisfiableRestricciones: Range

Qué hacer: Range: bytes=0-(size_bytes-1)
Política de reintentos: Reintenta después de corregir la solicitud.

Respuesta

{
  "error": {
    "code": "request.range_not_satisfiable",
    "fields": null,
    "message": "The requested byte range is unavailable."
  },
  "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.

Respuesta

{
  "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 en Retry-After. Si repites una escritura, mantén el mismo cuerpo de la solicitud y el mismo valor de Idempotency-Key.

Respuesta

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

429capacity.wait_timeoutSe agotó 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 en Retry-After. Si repites una escritura, mantén el mismo cuerpo de la solicitud y el mismo valor de Idempotency-Key.

Respuesta

{
  "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 en Retry-After. Si repites una escritura, mantén el mismo cuerpo de la solicitud y el mismo valor de Idempotency-Key.

Respuesta

{
  "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: Espera un momento antes de repetir la solicitud. Si vuelve a aparecer el error 500, contacta con el soporte técnico de Shopently e incluye el identificador de la solicitud.
Política de reintentos: Puedes volver a intentar leer los datos tras una breve pausa. Al repetir una escritura, usa el mismo valor de Idempotency-Key y mantén el cuerpo de la solicitud sin cambios.

Respuesta

{
  "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.

Respuesta

{
  "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: Si la respuesta incluye la cabecera Retry-After, espera los segundos indicados antes de volver a intentarlo. Si no la incluye, espera un momento. Si el error persiste, contacta con el soporte técnico de Shopently e incluye el identificador de la solicitud.
Política de reintentos: Vuelve a intentarlo después de esperar como se indica arriba. Al repetir una escritura, usa el mismo valor de Idempotency-Key y mantén el cuerpo de la solicitud sin cambios.

Respuesta

{
  "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: Si la solicitud modificaba datos, comprueba si los cambios se guardaron en la tienda. No recibir una respuesta no significa que la escritura haya fallado. Si el error persiste, contacta con el soporte técnico de Shopently e incluye el identificador de la solicitud.
Política de reintentos: Puedes volver a intentar leer los datos tras una breve pausa. Al repetir una escritura, usa el mismo valor de Idempotency-Key y mantén el cuerpo de la solicitud sin cambios.

Respuesta

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