Códigos de error

Códigos de estado HTTP de Listings API, códigos de error SYxxxxx de Listings y Social y las tres estructuras de respuesta de error de la API v4.

Listings API utiliza códigos de estado HTTP convencionales para indicar el resultado de una solicitud. Los códigos de error llevan el prefijo SY y se incluyen en la cadena message del error, con el formato SYxxxxx: <human-readable reason>.

Códigos de estado HTTP

HTTP status code summary

Estado	Significado	Código `SY` habitual	Excepción del Python SDK
`200 OK`	La solicitud se completó correctamente. En las escrituras, comprueba también el cuerpo de la respuesta (consulta más abajo).	-	-
`400 Bad Request`	Solicitud mal formada, filtro que no se puede analizar, valor de enumeración no válido o ID mal formado.	`SY90006`, `SY90001`	`ValidationError`
`401 Unauthorized`	La clave de API falta, está mal formada o ha sido revocada. ¿Aún no tienes una clave? Obtén un pase de un día gratuito para el entorno de pruebas cuando esté disponible.	`SY90005`	`AuthenticationError`
`402 Payment Required`	La cuenta tiene una factura pendiente de pago, por lo que el acceso a la API está suspendido. Una factura pendiente de pago que corresponda únicamente a Social suspende solo los endpoints de Social. Consulta `payment_required` y `social_payment_required`.	-	`APIError`
`403 Forbidden`	La clave es válida, pero no tiene permiso para acceder al recurso.	`SY90003`	`PermissionDeniedError`
`404 Not Found`	La ruta, o un recurso identificado mediante un ID, no existe.	`SY90002`	`NotFoundError`
`422 Unprocessable Entity`	La solicitud estaba bien formada, pero no se pudo procesar un valor (por ejemplo, una categoría desconocida o ambigua).	-	`ValidationError`
`429 Too Many Requests`	Has superado el límite de solicitudes de tu plan. Respeta la cabecera `Retry-After`.	-	`RateLimitError`
`5xx`	Un error del servidor. Es seguro reintentar una lectura con intervalos de espera crecientes; consulta la advertencia sobre escrituras más abajo antes de repetir una escritura.	`SY90007`	`InternalServerError`

Tres estructuras de respuesta

La mayoría de los fallos incluyen una matriz errors, ya sea en el nivel superior o anidada dentro del resultado de la operación, como muestran las secciones siguientes. Algunos fallos devuelven en su lugar un único objeto error: la limitación de solicitudes (429) y algunos fallos a nivel de solicitud (400/500 con un code como INTERNAL_SERVER_ERROR). Comprueba ambas posibilidades: errors es una matriz y error es un objeto.

1. A nivel de solicitud: `errors[]` en el nivel superior

Los fallos de autenticación, autorización y solicitudes mal formadas interrumpen el procesamiento antes de que se ejecute la operación. Devuelven el estado 4xx correspondiente (indicado arriba) con el error en el nivel superior de la respuesta.

JSON

{  "data": { "createLocation": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

2. Validación de escrituras: `data.<operation>.errors[]` anidado

Una solicitud de creación, actualización o publicación que, por lo demás, esté bien formada devuelve HTTP 200. Si los datos de entrada incumplen una regla de negocio, el fallo se indica en data.<operation>.errors, anidado dentro de la carga útil de la propia operación. Si la operación se completa correctamente, esta matriz está presente y vacía ("errors": []).

JSON

{  "data": {    "createLocation": {      "errors": [        { "message": "SY10126: City is Mandatory" },        { "message": "SY10010: state_iso" }      ],      "location": null    }  }}

3. A nivel de pasarela: un único objeto `error` en el nivel superior

La limitación de solicitudes y los fallos inesperados de la pasarela interrumpen el procesamiento antes de la traducción y devuelven un objeto error con un code, un message y un correlation_id. Consulta rate_limited más abajo para ver el cuerpo de 429.

Lee siempre data.<operation>.errors en una escritura, incluso con un 200 que contenga un objeto data.<operation> con datos: una escritura puede fallar parcialmente e indicarlo aquí.

Una respuesta 402 Payment Required no tiene un contenedor error: code, message, doc_url y, cuando hay una factura pendiente de pago, pay_url están en el nivel superior. Consulta payment_required más abajo.

Reintentar una escritura tiene un coste

La API v4 no admite Idempotency-Key: se ignora la cabecera y ningún endpoint detecta las escrituras repetidas. Una llamada de creación, actualización o publicación que agote el tiempo de espera o devuelva un 5xx puede haber guardado los cambios en el servidor, por lo que reintentar sin comprobarlo puede producir una ubicación, una publicación o una respuesta a una reseña duplicadas.

Reintenta las lecturas libremente con intervalos de espera crecientes. Para una escritura, realiza primero una lectura de comprobación: busca el registro mediante una clave que controles (storeId, un código de tienda, la lista de respuestas de la interacción) y repite la llamada solo si el registro realmente no existe.

Códigos habituales

Common SY error codes

Código	Mensaje	Estado HTTP	Significado
`SY90005`	`Invalid Token`	`401`	La clave de API falta, tiene un formato incorrecto o se ha revocado. Genera una nueva clave desde el panel y envíala como `Authorization: API <your-key>`.
`SY90001`	`Not authorized to access this resource`	`401` / `403`	La clave se ha rechazado para este recurso. Tanto el Python SDK como el de Node lanzan este error como `AuthenticationError`.
`SY90002`	`Invalid Id`	`404` / `400`	No se ha podido resolver un ID de ruta o de argumento (a menudo, un ID de Relay incorrecto o no codificado en base64).
`SY10126`	`City is Mandatory`	`200` (cuerpo de la respuesta)	Se ha omitido un campo obligatorio (`city`) en los datos de entrada.
`SY10010`	`state_iso`	`200` (cuerpo de la respuesta)	El valor de `stateIso` falta o no es válido. Consulta el endpoint de países y estados para ver los valores válidos.

Los códigos de validación del intervalo SY10xxx corresponden a un campo de entrada específico; message indica el nombre del campo o de la regla que ha fallado. Los códigos de autenticación y autorización del intervalo SY90xxx se aplican a toda la solicitud y llegan en el nivel superior con el estado correspondiente.

Códigos de cuentas conectadas

Los códigos del intervalo SY810xx proceden de los endpoints de Connected Accounts que importan o vinculan una ficha de una plataforma de publicación. Llegan anidados en el cuerpo de la respuesta con un HTTP 200 (estructura de respuesta 2 anterior), así que lee data.<operation>.errors incluso cuando el estado indique que la operación se ha completado correctamente.

SY810xx connected-account and import codes

Código	Significado	Qué hacer
`SY81019`	No se ha podido identificar a ningún usuario de la cuenta asociada a la clave.	Contacta con soporte: la cuenta no tiene ningún usuario principal activo.
`SY81066`	`connectedAccountId` no existe o la cuenta está archivada.	Vuelve a leer el ID de `GET /connected-accounts`.
`SY81067`	No se ha podido decodificar o resolver `connectedAccountListingId`.	Vuelve a obtenerlo de `id` de un registro de connected-account-listings.
`SY81068`	Esa ficha ya está vinculada a una ubicación.	Desconéctala primero o elige otra ficha.
`SY81069`	Las credenciales de la cuenta conectada ya no son válidas.	Vuelve a conectar la cuenta mediante connect-google o connect-facebook.
`SY81070`	La ficha no pertenece a la cuenta conectada que has indicado.	Asocia cada ficha con la cuenta de la que procede. Una causa habitual es obtener fichas sin incluir `connectedAccountId` en el cuerpo, lo que devuelve las fichas de otra cuenta.
`SY81071`	Se ha producido un error inesperado al crear la ubicación.	Vuelve a intentarlo; si el error persiste, contacta con soporte.
`SY81072`	La creación de la ubicación ha fallado durante su construcción o guardado.	Vuelve a intentarlo; si el error persiste, contacta con soporte.
`SY81073`	El tipo de ficha no es compatible con la importación.	Solo se pueden importar fichas de Google y Facebook.
`SY81074`	Google no ha devuelto datos de la ficha.	Confirma que la ficha sigue existiendo y que la cuenta sigue gestionándola.
`SY81075`	Se ha superado el límite de solicitudes de la API de Google.	Vuelve a intentarlo más tarde, aumentando progresivamente el tiempo de espera entre intentos.
`SY81076`	No se ha podido obtener la ficha de Google.	Vuelve a intentarlo; comprueba los permisos de Google de la cuenta.
`SY81077`	No se ha podido determinar el país a partir de la página de Facebook.	Añade un país a la dirección de la página en Facebook y vuelve a intentarlo.
`SY81078`	No se han podido construir los datos de la ubicación a partir de la página de Facebook.	Vuelve a intentarlo; si el error persiste, contacta con soporte.
`SY81081`	La ficha no tiene configurada una categoría principal.	Configura una categoría principal en la ficha y vuelve a intentarlo.
`SY81082`	El país de la ficha no es compatible.	Consulta el endpoint de países y estados para ver los países compatibles.
`SY81083`	No se ha podido importar la ficha de Google.	Contacta con soporte e incluye la marca de tiempo.
`SY81084`	Se ha producido un error interno al preparar la importación de Facebook.	Vuelve a intentarlo; si el error persiste, contacta con soporte e incluye la marca de tiempo.
`SY81085`	No se ha podido importar la página de Facebook.	Contacta con soporte e incluye la marca de tiempo.
`SY81086`	Una regla de negocio ha rechazado la creación de la ubicación. El campo anidado `message` contiene el código subyacente, por ejemplo, `SY10151` cuando la cuenta no tiene capacidad disponible para más ubicaciones.	Lee el mensaje anidado; en el caso de `SY10151`, añade un complemento de ubicación o cambia a un plan superior.
`SY81087`	La solicitud de creación de la ubicación ha fallado.	Vuelve a intentarlo; si el error persiste, contacta con soporte e incluye la marca de tiempo.
`SY81088`	La creación de la ubicación ha fallado por un motivo no reconocido.	Contacta con soporte e incluye la marca de tiempo.
`SY81089`	Una llamada a un servicio interno ha devuelto un estado que no indica éxito. No es un problema de tu solicitud.	Vuelve a intentarlo una vez; si el error persiste, contacta con soporte e incluye la marca de tiempo para que podamos rastrear la llamada interna.
`SY81090`	Se ha producido un error inesperado durante la llamada interna de creación de la ubicación.	Vuelve a intentarlo; si el error persiste, contacta con soporte e incluye la marca de tiempo.

Los códigos del rango SY950xx proceden de los endpoints de Social: marcas, conexiones y publicaciones en redes sociales. Al igual que los códigos de las cuentas conectadas, llegan anidados en el cuerpo de la respuesta de un HTTP 200, así que lee data.<operation>.error (y data.<operation>.errors en las rutas de operaciones masivas) incluso cuando el estado indique éxito.

SY950xx Social codes

Código	Significado	Qué hacer
`SY95041`	La cuenta ha alcanzado su límite de marcas. No puede producirse en un plan de API: las marcas son ilimitadas en ese plan.	No tienes que hacer nada en un plan de API. Si alguna vez lo ves, notifícalo: `GET /social/limits` debería devolver `brands: null`.
`SY95042`	La cuenta ha alcanzado su límite de conexiones para el período de facturación actual.	El límite se compara con `usage.connections` de `GET /social/limits`, el recuento facturable: las conexiones activas ahora más las liberadas durante este período. Una plaza liberada al desconectar o al archivar una marca queda reservada hasta que finaliza el período, por lo que una desconexión reciente no elimina este error. Vuelve a vincular una de las cuentas que liberaste a la marca a la que estaba vinculada (gratis, reutiliza esa plaza), compra otro paquete de 5 conexiones (inmediato) o espera a la renovación, cuando se recuperan las plazas `usage.connectionsReleased`. Vincular una cuenta liberada a una marca diferente no reutiliza la plaza. Consulta Planes y complementos.
`SY95043`	No hay ninguna marca con ese ID en esta cuenta, o la marca está archivada.	Vuelve a leer el ID en `GET /social/brands`. Los ID de marca son UUID simples, no ID de Relay en Base64.
`SY95044`	Esa plataforma no está habilitada para esta cuenta.	El plan de Social de la cuenta no incluye la plataforma que has solicitado conectar. Contacta con soporte o elige una plataforma incluida en la cuenta.
`SY95045`	La marca no tiene ningún canal conectado para esa plataforma.	Dirige al usuario a un enlace de conexión para esa plataforma, o elimínala de `platforms`. También aparece cuando el canal se desconectó después de que se programara la publicación.
`SY95046`	La programación o la zona horaria no es válida.	Envía `scheduledAt` o `scheduleDate` + `scheduleTime`, nunca ambas opciones. `scheduledAt` necesita un desfase respecto a UTC; `scheduleTime` es `HH:MM`. Las zonas horarias son identificadores de IANA (`tzCode`).
`SY95047`	No hay ningún trabajo masivo con ese ID en esta cuenta.	Vuelve a leer `job.id` en la respuesta de creación masiva. Los trabajos no se conservan indefinidamente.
`SY95048`	La solicitud masiva supera el límite de filas.	Envía como máximo 500 filas por solicitud y divide el resto en lotes adicionales. No se creó nada.
`SY95049`	La URL de redirección no es válida.	`redirectUrl` y `errorUrl` de un enlace de conexión deben ser URL `https` absolutas que controles.
`SY95050`	La validación masiva falló; consulta los errores de cada fila.	No se creó nada. Lee `job.results[]`: cada fila rechazada incluye su `index` con base 0, su `clientReference` y el motivo en `errors[]`. Corrige esas filas y vuelve a enviar el lote completo.
`SY95051`	La marca no ha cumplido el requisito de antigüedad de 90 días.	Una marca no se puede archivar hasta que tenga 90 días de antigüedad. La respuesta también indica `status: "TENURE_NOT_MET"` y no se ha cambiado nada. Vuelve a intentarlo después del día 90, cuando la marca y sus conexiones se archivan inmediatamente, aunque sus plazas de conexión quedan reservadas hasta el final del período de facturación. Consulta la regla de antigüedad.
`SY95052`	El canal conectado no pertenece a esta marca.	Asocia cada conexión con la marca en la que se creó. Es habitual cuando se construye una llamada de estadísticas a partir de una publicación de una marca y el ID de canal de otra marca.

SY95042 y SY95044 son fallos relacionados con las prestaciones del plan, no errores de entrada: volver a intentarlo sin cambiar el plan fallará de la misma manera. SY95045, SY95046, SY95049 y SY95052 son errores de entrada que se pueden corregir en la siguiente solicitud.

Códigos de derechos de acceso a Listings

Listings plan codes

Código	Significado	Qué hacer
`SY10150`	La cuenta ha alcanzado su límite de ubicaciones.	Archiva una ubicación, compra un complemento de ubicación adicional o cambia a un plan superior. Consulta Planes y complementos.
`SY10151`	La cuenta no tiene plazas disponibles para ubicaciones en este plan. En un pase de un día del entorno de pruebas, sus 2 ubicaciones están en uso.	Las mismas soluciones que para `SY10150`. Con un pase de un día, actualiza una ubicación existente o elige un plan de pago. También aparece anidado dentro de `SY81086` cuando se crea una ubicación a partir de una ficha de una cuenta conectada.
`SY10152`	La ubicación no lleva activa el tiempo suficiente para poder archivarse.	Las ubicaciones deben permanecer activas durante el período mínimo de permanencia de la cuenta, 90 días de forma predeterminada, antes de que `POST /locations/archive` las acepte. Espera a que se cumpla el período de permanencia.
`SY10155`	La cuenta no tiene un plan de Listings, por lo que no se pueden crear ubicaciones.	La clave de API pertenece a una cuenta sin suscripción a Listings, como una cuenta que solo tiene Social. Las ubicaciones forman parte del producto Listings; suscríbete a él antes de llamar a `POST /locations`.

`rate_limited`

429 Too Many Requests: la cuenta ha superado el límite de solicitudes de su plan. El cuerpo es la respuesta de error estándar que contiene una indicación retry_after_seconds, un correlation_id que debes incluir en las solicitudes de soporte y un doc_url que enlaza a esta sección:

JSON

{  "error": {    "code": "RATE_LIMITED",    "message": "Too many requests. Slow down.",    "retry_after_seconds": 30,    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#rate_limited"  }}

Espera el tiempo indicado por retry_after_seconds (o por la cabecera Retry-After, si está presente) y vuelve a intentarlo con una espera exponencial entre intentos. Consulta Límites de solicitudes para conocer los límites de cada plan y una implementación de referencia de la espera entre intentos.

`payment_required`

402: El último pago de esta cuenta no se ha completado, por lo que todos los endpoints de /api/v4 están en pausa. El cuerpo incluye pay_url, la página de Stripe de la factura pendiente de pago, cuando está disponible, y la cabecera de respuesta X-Error-Code contiene el mismo code. Aún puedes abrir la página de facturación en el panel para pagar.

JSON

{  "code": "payment_required",  "message": "This account has an unpaid invoice, so API access is paused. Pay the invoice to restore access.",  "pay_url": "https://invoice.stripe.com/i/acct_123/test_abc",  "doc_url": "https://listingsapi.com/docs/error-codes#payment_required"}

El acceso se restablece en un plazo de un minuto tras el pago de la última factura pendiente. Si la factura sigue sin pagarse 3 días después del primer pago fallido, se cancela la suscripción a Listings y se archivan las ubicaciones de la cuenta. Si la cuenta también tiene una suscripción activa a Social, conserva el acceso a Social; de lo contrario, se cierra la cuenta y sus claves de API dejan de funcionar.

`social_payment_required`

402: El último pago de la suscripción a Social no se ha completado, por lo que los endpoints de Social (/api/v4/social/*) están en pausa. Los endpoints de Listings siguen funcionando. El cuerpo tiene los mismos campos que payment_required, con "code": "social_payment_required". Si la factura sigue sin pagarse 3 días después del primer pago fallido, se cancela la suscripción a Social y se archivan las marcas de la cuenta. Si la cuenta no tiene una suscripción a Listings, se cierra y sus claves de API dejan de funcionar.

Errores del plano de control del portal de desarrolladores

Los endpoints de gestión de cuentas y claves del portal de desarrolladores (las rutas de API propias del panel) devuelven una única respuesta de error estructurada, distinta de los formatos errors[] de REST anteriores. Cada code contiene un correlation_id y un doc_url que enlaza a la sección correspondiente de esta página.

JSON

{  "error": {    "code": "AUTH_INVALID_KEY",    "message": "Session is invalid or expired.",    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#auth_invalid_key"  }}

`auth_missing_key`

401: No se ha proporcionado ninguna credencial. Vuelve a iniciar sesión o envía tu clave como Authorization: API <your-key>.

`auth_invalid_key`

401: La sesión o la clave no es válida o ha caducado. Vuelve a autenticarte o emite una nueva clave desde el panel.

`auth_insufficient_scope`

403: La credencial es válida, pero no permite realizar esta acción. Una clave con permisos de lectura no puede llamar a endpoints de escritura; emite una clave de escritura si la necesitas.

`not_found`

404: El recurso solicitado, o un recurso identificado por su ID, no existe.

`conflict`

409: La solicitud entra en conflicto con el estado actual del recurso (por ejemplo, al revocar una clave que ya está revocada).

`validation_failed`

422: El cuerpo de la solicitud no ha superado la validación. Los campos field y details de la respuesta identifican el dato de entrada que ha causado el error.

`internal_error`

500: Un error inesperado del servidor. Reintenta una lectura con una espera exponencial entre intentos; para una escritura, primero vuelve a leer el registro (consulta Reintentar una escritura no es gratis). Incluye el correlation_id si contactas con soporte.

`dependency_unavailable`

503: Un servicio del que depende la API no está disponible temporalmente. Vuelve a intentarlo con una espera entre intentos.

Para 429, consulta rate_limited más arriba.

Gestión de errores en el código

Comprueba primero el estado HTTP; después, para las operaciones de escritura, busca un array errors anidado en el cuerpo de la respuesta:

Python

from listingsapi import APIError, ListingsAPI client = ListingsAPI(api_key=os.environ["LISTINGSAPI_KEY"]) try:    location = client.locations.create(input=payload)except APIError as e:    # Raised for a non-2xx status (AuthenticationError, ValidationError, and    # so on) and for an error payload returned inside a 200 body.    raise RuntimeError(f"Listings API error: {e}") from e

Al usar directamente la API HTTP, las mismas dos comprobaciones se realizan de forma explícita: primero el código de estado y después el contenido de la respuesta:

Python

resp = requests.post(    "https://listingsapi.com/api/v4/locations",    headers={"Authorization": f"API {os.environ['LISTINGSAPI_KEY']}"},    json=payload,    timeout=30,)resp.raise_for_status()body = resp.json() op = (body.get("data") or {}).get("createLocation") or {}if op.get("errors"):    messages = [e["message"] for e in op["errors"]]    raise RuntimeError(f"Listings API error: {messages}")

El Python SDK realiza ambas comprobaciones por ti: asigna a cada estado HTTP una excepción de un tipo específico y también lanza una excepción cuando se devuelven datos de error dentro de un cuerpo 200.