Errores
Errores
Cada fallo lleva un código estable. Ramifique por el código y nunca por el mensaje: la redacción puede cambiar en cualquier momento, el código no.
Las rutas, los métodos, los ámbitos, los nombres de campo y los códigos de error se publican en inglés, porque el inglés es el idioma de la propia interfaz: es lo que quien llama escribe o compara. Lo mismo ocurre con cada ejemplo de código, cada carga JSON y la frase exacta que lleva una respuesta de error: /v1 no lee Accept-Language, y traducir lo que la API envía realmente sería describirla mal. Todo lo que se escribe sobre ello sigue el idioma de esta página.
El sobre de error
Toda respuesta fuera de 2xx tiene la misma forma. documentation_url apunta directamente a la entrada correspondiente más abajo, y request_id es el valor que hay que citar en una consulta de soporte. details lleva contexto legible por máquina: para un cuerpo rechazado son los issues, cada uno un JSON Pointer al campo defectuoso.
{
"error": {
"code": "validation_failed",
"message": "The request body failed validation.",
"documentation_url": "https://passportcraft.com/docs/api/errors#validation_failed",
"request_id": "req_9Fv2KpQ0aXbT4Lmn",
"details": {
"issues": [
{ "source": { "pointer": "/data/product_name" }, "rule": "required" }
]
}
}
}Códigos
Cada código está enlazado desde la respuesta que lo lleva, así que a esta página se suele llegar directamente en la entrada que hace falta.
invalid_key
401La clave de API indicada no es válida.
La API devuelveThe API key provided is not valid.
Cualquier endpoint puede devolverlo.
key_revoked
401Esta clave de API ha sido revocada.
La API devuelveThis API key has been revoked.
Cualquier endpoint puede devolverlo.
key_expired
401Esta clave de API ha caducado.
La API devuelveThis API key has expired.
Cualquier endpoint puede devolverlo.
key_rotated
401Esta clave de API se sustituyó en una rotación y su ventana de solapamiento ya se cerró.
La API devuelveThis API key was replaced by a rotation and its overlap window has closed.
Cualquier endpoint puede devolverlo.
mode_mismatch
400El prefijo de la clave no coincide con la credencial. Compruebe si quería una clave de prueba o una de producción.
La API devuelveThe key prefix does not match the credential. Check whether you meant a test or a live key.
Cualquier endpoint puede devolverlo.
insufficient_scope
403Esta credencial no lleva el ámbito que exige esta operación.
La API devuelveThis credential does not carry the scope required for this operation.
Qué endpoints lo devuelven
- get
/organizations/{organization}/capabilities - get
/organizations/{organization}/events - get
/organizations/{organization}/passports - post
/organizations/{organization}/passports - get
/organizations/{organization}/passports/{id} - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/validate - get
/organizations/{organization}/passports/{id}/links - get
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/affichage - get
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/units - get
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/passports/{id}/documents - delete
/organizations/{organization}/passports/{id}/documents/{documentId} - post
/organizations/{organization}/imports - get
/organizations/{organization}/imports - get
/organizations/{organization}/imports/{id}
organization_not_found_or_not_granted
404No existe esa organización.
La API devuelveNo such organization.
Qué endpoints lo devuelven
- get
/organizations/{organization}/capabilities - get
/organizations/{organization}/events - get
/organizations/{organization}/passports - post
/organizations/{organization}/passports - get
/organizations/{organization}/passports/{id} - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/validate - get
/organizations/{organization}/passports/{id}/links - get
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/affichage - get
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/units - get
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/passports/{id}/documents - delete
/organizations/{organization}/passports/{id}/documents/{documentId} - post
/organizations/{organization}/imports - get
/organizations/{organization}/imports - get
/organizations/{organization}/imports/{id}
resource_not_found
404No existe ese recurso.
La API devuelveNo such resource.
Qué endpoints lo devuelven
- get
/categories/{category}/schema - get
/organizations/{organization}/passports/{id} - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/validate - get
/organizations/{organization}/passports/{id}/links - get
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/affichage - get
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/units - get
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/passports/{id}/documents - delete
/organizations/{organization}/passports/{id}/documents/{documentId} - get
/organizations/{organization}/imports/{id}
wildcard_not_supported
400El comodín de organización "-" está reservado y todavía no se admite.
La API devuelveThe "-" organization wildcard is reserved and not yet supported.
Qué endpoints lo devuelven
- get
/organizations/{organization}/capabilities - get
/organizations/{organization}/events - get
/organizations/{organization}/passports - post
/organizations/{organization}/passports - get
/organizations/{organization}/passports/{id} - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/validate - get
/organizations/{organization}/passports/{id}/links - get
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/affichage - get
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/units - get
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/passports/{id}/documents - delete
/organizations/{organization}/passports/{id}/documents/{documentId} - post
/organizations/{organization}/imports - get
/organizations/{organization}/imports - get
/organizations/{organization}/imports/{id}
validation_failed
422El cuerpo de la solicitud no superó la validación.
La API devuelveThe request body failed validation.
Qué endpoints lo devuelven
- post
/organizations/{organization}/passports - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/validate - post
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/imports
invalid_request
400No se ha podido interpretar la solicitud.
La API devuelveThe request could not be understood.
Cualquier endpoint puede devolverlo.
method_not_allowed
405El endpoint existe, pero no responde a este método HTTP. La cabecera Allow del rechazo enumera los métodos a los que sí responde.
La API devuelveThis endpoint does not support that HTTP method. The Allow header lists the ones it does.
payload_too_large
413El cuerpo de la solicitud supera lo que acepta este endpoint. details.limit_bytes indica el tope aplicado.
La API devuelveThe request body is larger than this endpoint accepts.
Cualquier endpoint puede devolverlo.
unsupported_media_type
415El cuerpo de la solicitud no llegó como application/json.
La API devuelveThe request body must be sent as application/json.
Qué endpoints lo devuelven
- post
/organizations/{organization}/passports - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/validate - post
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/imports
idempotency_conflict
409Esta Idempotency-Key ya se usó con un cuerpo de solicitud distinto.
La API devuelveThis Idempotency-Key was already used with a different request body.
Qué endpoints lo devuelven
- post
/organizations/{organization}/passports - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/documents - post
/organizations/{organization}/imports
precondition_failed
412El recurso cambió desde la versión que usted indicó.
La API devuelveThe resource changed since the version you supplied.
resource_busy
409Otra petición está modificando este recurso. Espere el tiempo indicado en la cabecera Retry-After y vuelva a intentarlo.
La API devuelveAnother request is modifying this resource. Wait for the Retry-After header, then retry.
Qué endpoints lo devuelven
cursor_invalid
400El cursor de paginación no es válido, ha caducado o se envió con otros filtros.
La API devuelveThe pagination cursor is invalid, expired, or was sent with different filters.
no_subscription
402Esta organización no tiene una suscripción activa.
La API devuelveThis organization has no active subscription.
Qué endpoints lo devuelven
- post
/organizations/{organization}/passports - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/documents - delete
/organizations/{organization}/passports/{id}/documents/{documentId} - post
/organizations/{organization}/imports
payment_overdue
402La publicación está desactivada mientras haya un pago pendiente.
La API devuelvePublishing is disabled while payment is overdue.
Qué endpoints lo devuelven
- post
/organizations/{organization}/passports - patch
/organizations/{organization}/passports/{id} - post
/organizations/{organization}/passports/{id}/publish - post
/organizations/{organization}/passports/{id}/unpublish - post
/organizations/{organization}/passports/{id}/trash - post
/organizations/{organization}/passports/{id}/restore - post
/organizations/{organization}/passports/{id}/affichage - post
/organizations/{organization}/passports/{id}/units - post
/organizations/{organization}/passports/{id}/documents - delete
/organizations/{organization}/passports/{id}/documents/{documentId} - post
/organizations/{organization}/imports
gtin_required
422Hace falta un GTIN antes de poder publicar este pasaporte.
La API devuelveA GTIN is required before this passport can be published.
wrong_status
409El pasaporte no está en un estado que permita esta operación.
La API devuelveThe passport is not in a status that allows this operation.
Qué endpoints lo devuelven
not_trashed
409Solo se puede restaurar un pasaporte que esté en la papelera.
La API devuelveOnly a trashed passport can be restored.
Qué endpoints lo devuelven
publish_limit_reached
402Esta organización ha agotado todas las plazas de publicación que permite su plan.
La API devuelveThis organization has used every publish slot its plan allows.
Qué endpoints lo devuelven
unit_limit_reached
402Este pasaporte lleva más unidades de las que permite el plan.
La API devuelveThis passport carries more units than the plan allows.
document_missing
422Un campo obligatorio se cubre únicamente con un documento que ya no está adjunto.
La API devuelveA required field is satisfied only by a document that is no longer attached.
Qué endpoints lo devuelven
delegation_required
403La presentación exige una delegación activa, verificada contra el portal en el momento de la llamada.
La API devuelveFiling requires an active delegation, verified against the portal at call time.
Qué endpoints lo devuelven
attestation_required
403Esta operación exige una declaración responsable aceptada por una persona identificada de la marca.
La API devuelveThis operation requires an attestation accepted by a named person at the brand.
Qué endpoints lo devuelven
test_mode_refused
403Las credenciales de modo de prueba no pueden realizar esta operación.
La API devuelveTest-mode credentials cannot perform this operation.
Qué endpoints lo devuelven
rate_limited
429Demasiadas solicitudes.
La API devuelveToo many requests.
Cualquier endpoint puede devolverlo.
internal_error
500Algo ha fallado por nuestra parte.
La API devuelveSomething went wrong on our side.
Cualquier endpoint puede devolverlo.
configuration_error
500El servicio está mal configurado. No es un problema de su solicitud.
La API devuelveThe service is misconfigured. This is not a problem with your request.
Cualquier endpoint puede devolverlo.
Avisos
Un aviso no es un rechazo. Llega junto a un 200, en una llamada que salió bien, y señala algo que conviene atender.
environmental_claim_detected
200El pasaporte contiene lenguaje de alegación ambiental. La publicación salió bien y el pasaporte está en línea. Desde el 27 de septiembre de 2026, la Directiva (UE) 2024/825 exige que el comerciante que introduce el producto en el mercado disponga de justificación para esas afirmaciones.