Errores, identificador de petición y reintentos
Cómo es un error de la API externa, qué significa cada errorCode, quién lo arregla, qué cabeceras leer y cuándo merece la pena reintentar.
Actualizado el . 38 min de lectura
Incluido en todos los planes. Ver precios
Todos los errores de la API externa tienen la misma forma y casi todos traen un código estable, errorCode, para que tu programa decida sin leer el texto. Desde el sistema de pruebas, cada error de /api/external/v1 dice además quién puede arreglarlo (fixedBy) y dónde está explicado (docsUrl): esa dirección lleva a su apartado de esta página.
Si es la primera vez que integras, o lo hace tu asistente de IA, empieza por Integrar con un asistente de IA: explica el ciclo completo de diagnosticar, comprobar y leer el error.
La forma de un error
{
"statusCode": 403,
"message": "A esta aplicación le falta el permiso de la API «Emitir facturas» (crm:invoices:issue) para esta operación. Lo concede un administrador de la organización en UTILIA OS, en la ficha de la aplicación, Configuración › Ajustes › Permisos.",
"error": "FORBIDDEN",
"errorCode": "INSUFFICIENT_SCOPE",
"requiredScopes": ["crm:invoices:issue"],
"fixedBy": "organization",
"docsUrl": "https://os.utilia.ai/docs/developers/getting-started/errors-and-retries#insufficient_scope",
"retryable": false,
"timestamp": "2026-10-21T10:31:12.000Z",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}- statusCodenumberobligatorio
- Código HTTP de la respuesta.
- messagestringobligatorio
- Explicación en castellano para tu registro o para una persona. Puede llevar datos del caso: no decidas por él.
- errorstringobligatorio
- Nombre del estado HTTP en mayúsculas (BAD_REQUEST, NOT_FOUND...). Para decidir está errorCode.
- errorCodestring
- Código estable del caso. Es lo que lee tu programa. Cada uno tiene su apartado en esta página.
- fixedByenum
- Quién puede arreglarlo: developer, organization o utilia. Solo en /api/external/v1.
- docsUrlstring
- Dirección pública de la explicación del código, con su ancla. Sin código, la del estado HTTP (#http-404). Solo en /api/external/v1.
- requestIdstring
- Identificador de la petición, el mismo que la cabecera X-Request-Id. Cítalo al pedir ayuda.
- timestampstringobligatorio
- Fecha y hora de la respuesta (ISO 8601).
- requiredScopesstring[]
- Solo en el 403 INSUFFICIENT_SCOPE: los permisos de la API que le faltan a la aplicación.
- retryableboolean
- En todo error de /api/external/v1. true: la misma petición puede funcionar si la repites pasado un rato (con la misma clave de idempotencia, si la lleva). false: repetirla no cambiará nada. Es el valor de cada código en este catálogo, salvo en los errores que deciden el suyo según el caso, como un PDF que todavía se está preparando. Manda sobre el estado HTTP.
- retryAfterSecondsnumber
- Con retryable: true y en algunos 429, los segundos que conviene esperar antes de repetirla.
Algunos errores añaden campos propios en la raíz, junto a errorCode: los de plan traen moduleKey o capabilityKey (Errores de plan), los de facturas missingFields, lineNumber o seriesCode, y los de fusión mergedIntoId. Con los SDK se leen en error.details.
No pintes el objeto de error
El cuerpo del error es un objeto, no un texto. Si lo pasas tal cual a un aviso o a un componente de React, la pantalla se rompe con «Objects are not valid as a React child». Muestra message, decide con errorCode y guarda requestId.
Quién lo arregla
fixedBy dice quién puede resolverlo, no de quién es la culpa. Es la primera pregunta que debe hacerse tu programa, y sobre todo tu asistente de IA: si no te toca a ti, cambiar el código no lo arregla.
Los tres valores de fixedBy
Quien programa
developer
Un administrador de la organización
organization
Nosotros
utilia
Cabeceras que debes leer
- X-Request-Idstringobligatorio
- En todas las respuestas. Si tu petición trae uno (letras, números, guiones y guiones bajos, hasta 128 caracteres), se respeta; si no, se genera.
- X-Utilia-Quota-Limitnumber
- Peticiones por hora de la clave de tu aplicación. En toda respuesta a partir de identificar la aplicación.
- X-Utilia-Quota-Remainingnumber
- Las que te quedan en la ventana actual, contada ya esta petición.
- X-Utilia-Quota-Resetnumber
- Cuándo se vacía el contador, en segundos UNIX.
- Retry-Afternumber
- En un 429: los segundos que debes esperar. En el cupo por hora es lo que de verdad le queda a la ventana; en el freno por minuto y en las pruebas, lo que queda de su minuto.
- X-RateLimit-Limit / -Remaining / -Resetnumber
- Las del freno de ráfagas por minuto, no las del cupo por hora. Reset va en segundos relativos. En el 429 DIAGNOSTICS_RATE_LIMITED, las del cupo de esa prueba (6 o 5 al minuto), con Remaining a 0.
- X-Utilia-Ignored-Fieldsstring
- En una escritura que responde bien: los campos del cuerpo que se han descartado sin error, separados por coma y espacio (hasta 20, solo nombres, nunca valores). Casi siempre es un nombre mal escrito.
- X-Deprecation-Warningstring
- La llamada pasa sin un permiso que pronto será obligatorio. Nombra el permiso y la fecha. Nunca sale con un permiso crítico, que se exige siempre.
- X-Utilia-Api-Key-Expiresstring
- Llamas con la clave anterior, durante una renovación: hasta cuándo vale.
X-Utilia-Ignored-Fields es la más traicionera de olvidar: la respuesta es un 201 y el dato no se guarda. Si la ves, compara el nombre con la referencia de la ruta o pasa el cuerpo por la comprobación de peticiones, que dice lo mismo antes de enviar nada. Los límites y sus cifras están en Límites de uso y CORS.
Seguir una petición con X-Request-Id
Enviar tu propio identificador te permite seguir la misma petición en tus registros y en los nuestros: es lo primero que te pedirá soporte.
X-Api-Key: utl_tu_clave
X-Request-Id: pedido-8812-intento-1Cuándo reintentar
Reintenta solo cuando el fallo puede desaparecer por sí solo. Todo error de /api/external/v1 trae retryable, y manda él sobre el estado HTTP. Solo falta cuando la respuesta no es de la API: un fallo de red, un tiempo de espera agotado o una página de error de un intermediario.
¿Repito la petición?
¿El cuerpo del error trae retryable?
true:
Repite la misma petición
Espera retryAfterSeconds y mándala igual, con la misma idempotencyKey si la lleva.false:
No repitas
Repetirla dará lo mismo. Lee errorCode y fixedBy.No lo trae:
¿Es un 429?
Sí:
Espera Retry-After
429
Espera los segundos de la cabecera y reparte las llamadas en el tiempo.No:
¿Es un 5xx o un fallo de red?
Sí:
¿Es una lectura o lleva idempotencyKey?
Sí:
Repite con espera creciente
1, 2, 4 y 8 segundos con algo de azar, cuatro intentos como mucho y siempre la misma idempotencyKey.No:
Comprueba antes de repetir
Una escritura sin clave, como POST /tickets, pudo hacerse. Búscala (por ejemplo, en los tickets del usuario) y repítela solo si no está.
No, es otro 4xx:
Corrige antes de repetir
400, 401, 403, 404, 409 y 422 no cambian por repetir: arregla la petición, la clave, el permiso o el plan.
Lo crítico, en una frase: nunca repitas una escritura con una clave de idempotencia nueva, y nunca repitas una que no lleva clave sin comprobar antes si llegó a hacerse. Un 5xx o un corte de red no dicen si la operación se hizo: solo que no te llegó la respuesta. Los SDK, desde la 4.6.0, ya no repiten solos los POST sin clave de idempotencia y esperan lo que pide Retry-After; ver Gestión de errores del SDK y, para saber qué versión está publicada, Versiones y compatibilidad.
Repetir sin duplicar: idempotencyKey
En la API externa, la idempotencia es un campo del cuerpo, idempotencyKey (de 1 a 128 caracteres), y solo la admiten las operaciones que crean algo con dinero de por medio. No hay cabecera: Idempotency-Key no la lee ninguna ruta de /api/external/v1.
| Operación | idempotencyKey | Qué pasa al repetir con la misma |
|---|---|---|
POST /invoices | Opcional | Devuelve la factura original con su issuanceDeliveryStatus. Vale 24 horas desde que se creó la factura; una emisión que no llegó a completarse no caduca, y repetirla consulta su estado sin reemitir ni reenviar nada. |
POST /invoices/:id/rectifications | Obligatoria | Devuelve la misma rectificativa (idempotent: true) y reanuda lo que quedara pendiente. |
POST /invoices/:id/charge | Opcional | Durante 24 horas, devuelve el cobro ya iniciado en lugar de volver a cobrar. |
POST /invoices/:id/refund | Opcional | Durante 24 horas, devuelve el reembolso ya emitido. |
POST /subscriptions | Opcional | Durante 24 horas, devuelve la suscripción creada. |
POST /invoices/:id/scheduled-charges | Opcional | Durante 24 horas, devuelve el cobro programado ya creado. |
La clave identifica una operación junto con su cuerpo: la misma clave con otro cuerpo responde 409 (en facturas, rectificativas, cobros y reembolsos, BILLING_IDEMPOTENCY_CONFLICT). Usa una por operación de tu lado (por ejemplo, el identificador de tu pedido) y guárdala antes de llamar, para repetir con la misma si no llega la respuesta. El resto de escrituras, como abrir un ticket o identificar a un usuario, no tienen clave de idempotencia.
Emitir una factura puede tardar varios segundos
Pon a tu cliente HTTP un tiempo de espera de al menos 30 segundos para POST /external/v1/invoices. Si aun así se corta, repite con la misma idempotencyKey: si la primera sigue en marcha, recibes la misma factura con issuanceDeliveryStatus: processing, nunca una segunda. Ver Reintentar sin duplicar la factura.
Cómo leer el catálogo
Cada código tiene su apartado, con el ancla que usa docsUrl (el código en minúsculas, como #insufficient_scope). Debajo del nombre van tres datos: el estado HTTP, quién lo arregla (fixedBy) y si repetir la misma petición más tarde puede funcionar (el retryable que trae el código por defecto; los pocos errores que lo deciden según el caso lo explican en su apartado, y manda siempre el del cuerpo). Un código que no esté aquí se explica por su estado HTTP.
Credencial y acceso
API_KEY_REQUIRED
401 · Lo arregla quien programa · No se reintenta
La petición no trae la clave de la aplicación en la cabecera X-Api-Key. Envíala en cada petición: X-Api-Key: utl_....
API_KEY_INVALID
401 · Lo arregla quien programa · No se reintenta
La clave no existe, está desactivada o ha caducado. Comprueba que la copiaste entera y que es la vigente; si se renovó, usa la nueva. El mensaje es el mismo en los tres casos, a propósito.
API_KEY_NOT_LINKED
401 · Lo arregla quien programa · No se reintenta
La clave existe, pero no pertenece a ninguna aplicación externa: suele ser una clave de envío de leads (también empieza por utl_). Usa la clave de la aplicación, de su ficha en Ajustes, Creadas por tu empresa.
API_KEY_WRONG_KIND
401 · Lo arregla quien programa · No se reintenta
La credencial es de otro tipo: una clave de API de la organización (utk_) contra /api/external/v1, en X-Api-Key o en Authorization. La utk_ va en Authorization: Bearer contra las rutas de la aplicación (/api/...); aquí va la clave de la aplicación externa (utl_) en X-Api-Key. También lo recibes al revés: una utl_ en Authorization: Bearer contra una ruta de la aplicación. Cuál elegir está en Integrar con un asistente de IA.
API_KEY_WRONG_HEADER
401 · Lo arregla quien programa · No se reintenta
La clave de la aplicación ha llegado en Authorization: Bearer. Envíala en la cabecera X-Api-Key.
API_KEY_IN_URL_NOT_ALLOWED
401 · Lo arregla quien programa · No se reintenta
La clave llegó en la dirección, donde queda en registros, servidores intermedios e historial. Da igual el nombre del parámetro (apiKey, api_key, x-api-key...) y también cuenta una clave utl_… escrita como valor de otro parámetro. Envíala en X-Api-Key; para las conexiones de eventos en tiempo real, pide antes un pase de conexión. Los SDK lo hacen solos. La forma antigua, ?apiKey= en una conexión de eventos en tiempo real, se admite todavía y también dejará de admitirse: ver Eventos en tiempo real.
Si la petición trae la clave en la dirección y en la cabecera X-Api-Key, de momento entra por la cabecera, pero el diagnóstico avisa con el hallazgo key-in-url. Arréglalo cuanto antes, porque dejará de admitirse, y pide que se renueve la clave: la que viajó en la dirección puede estar expuesta.
STREAM_TOKEN_INVALID
401 · Lo arregla quien programa · No se reintenta
El pase de conexión no es válido, ya se usó o ha caducado. Cada pase sirve una vez: pide uno nuevo para cada conexión.
STREAM_TOKEN_UNAVAILABLE
503 · Lo arreglamos nosotros · Se puede reintentar
Ahora mismo no se puede emitir el pase de conexión. Repítelo a los pocos segundos.
STREAM_TOKEN_USER_REQUIRED
400 · Lo arregla quien programa · No se reintenta
En una aplicación con widget, el pase de la conexión de eventos de tickets necesita el usuario (userId). Añádelo a la petición del pase.
WIDGET_IDENTITY_REQUIRED
403 · Lo arregla quien programa · No se reintenta
La aplicación exige verificar a la persona del widget y la petición trae un userId sin su firma en la cabecera X-Utilia-User-Signature. Calcula en tu servidor la firma del userId con el secreto del widget (HMAC-SHA256 en hexadecimal) y pásasela al widget en userSignature. Ver Verificar la identidad en el widget.
WIDGET_IDENTITY_INVALID
403 · Lo arregla quien programa · No se reintenta
La firma de X-Utilia-User-Signature no corresponde a ese userId: se calculó para otro usuario, con un secreto que ya no vale o sobre un valor distinto del userId que manda el widget. Vuelve a calcularla en tu servidor con el secreto del widget vigente, sobre el userId exacto que recibe el widget.
WIDGET_IDENTITY_SECRET_MISSING
403 · Lo arregla la organización · No se reintenta
La aplicación exige verificar a la persona del widget y todavía no tiene secreto del widget, así que ninguna petición con userId puede pasar. Un administrador de la organización lo genera en la ficha de la aplicación y te lo pasa para firmar en tu servidor. Mientras tanto, la verificación se puede poner en el modo que solo registra los fallos.
APP_DISABLED
403 · Lo arregla la organización · No se reintenta
La aplicación está desactivada en UTILIA OS y todas sus llamadas se rechazan. La activa un administrador desde la ficha de la aplicación. También el diagnóstico (GET /external/v1/diagnostics) responde este 403: el hallazgo app-disabled solo se ve en la pestaña Pruebas del panel y por MCP.
APP_RESPONSIBLE_INACTIVE
403 · Lo arregla la organización · No se reintenta
La aplicación no tiene una persona responsable activa: nunca la tuvo, o está dada de baja o bloqueada. Sin ella se rechaza toda llamada, también la del diagnóstico. Un administrador nombra otra en la ficha de la aplicación. En el panel y por MCP, el diagnóstico lo explica con responsible-missing o responsible-inactive.
APP_RESPONSIBLE_PERMISSION_DENIED
403 · Lo arregla la organización · No se reintenta
La persona responsable no tiene en UTILIA OS el permiso que exige esta operación sobre ese registro. Lo comprueban las rectificativas, los cambios de una suscripción y los cobros programados; el resto de la API se rige por los permisos de la API de la aplicación. Se arregla en los permisos de esa persona, no en los de la aplicación.
ORIGIN_NOT_ALLOWED
403 · Lo arregla la organización · No se reintenta
Dos casos con el mismo código: el origen del navegador no está entre los dominios autorizados de la aplicación, o la operación solo se admite de servidor a servidor (como emitir una rectificativa) y llegó desde un navegador. El mensaje dice cuál. En el primero, un administrador añade el dominio; en el segundo, llama desde tu servidor.
CORS_ORIGIN_NOT_ALLOWED
403 · Lo arregla la organización · No se reintenta
El navegador llama desde un origen que la plataforma no tiene autorizado. Ver Límites de uso y CORS.
RATE_LIMIT_EXCEEDED
429 · Lo arregla quien programa · Se puede reintentar
Se ha agotado un cupo por hora: el de la aplicación, o el propio de una ruta (contactos, leads, clientes, sincronizar, buscar por correo o por NIF, o enviar facturas por correo). El mensaje dice cuál. Si es el de la aplicación, X-Utilia-Quota-Remaining te avisa antes de llegar; si llega con X-Utilia-Quota-Remaining mayor que cero, es el de la ruta. Espera los segundos de Retry-After (o de retryAfterSeconds, si viene en el cuerpo) y reparte las llamadas. Cada cupo y su cifra están en Los límites de un vistazo.
INSUFFICIENT_SCOPE
403 · Lo arregla la organización · No se reintenta
A la aplicación le falta un permiso de la API para esta operación. requiredScopes dice cuál, y el mensaje lo nombra con su etiqueta. Lo concede un administrador en los permisos de la API de la aplicación; si no lo necesitas, deja de llamar a esa ruta. El catálogo de permisos está en Permisos de la API.
El 403 solo nombra el permiso cuando depende de lo que pides: la ruta, un ?include= o un filtro. Cuando depende del dato, no hay 403: un contacto dado de baja o inactivo, leído sin crm:contacts:read:opted-out, responde 404 CONTACT_NOT_FOUND, igual que uno que no existe, para no confirmar que esa persona existe y se ha dado de baja.
Si UTILIA OS abre un periodo de transición para un permiso nuevo, la llamada sin él pasa hasta esa fecha con la cabecera X-Deprecation-Warning. Los permisos críticos, los de datos personales sensibles y los financieros (cobrar, devolver dinero, anular o rectificar facturas, entre otros), no tienen transición nunca: sin ellos, la llamada responde este 403 desde la primera vez.
SCOPE_NOT_ALLOWED_FROM_BROWSER
403 · Lo arregla quien programa · No se reintenta
La operación exige un permiso que no se usa con una clave que va en una página web. Una clave así la puede copiar cualquiera, así que desde un navegador solo valen los permisos del widget: tickets, sugerencias de IA de los tickets, archivos, users.identify y el envío de errores. Vale para cualquier aplicación, tenga o no dominios autorizados. notAllowedScopes dice qué permisos lo impiden. Llama a esa operación desde tu servidor, con la clave de una aplicación sin dominios autorizados. Una clave publicada (con dominios autorizados o usada desde un navegador) solo debe tener esos permisos: si tiene otros, retíralos o pasa esas operaciones a otra aplicación, porque la llamada puede responder este mismo 403 aunque no venga de un navegador. Ver Claves dentro de una página web.
SCOPE_NOT_ALLOWED_WITH_ALLOWED_ORIGINS
400 · Lo arregla la organización · No se reintenta
No lo devuelve /api/external/v1: llega al configurar la aplicación en el panel o por MCP. Una aplicación cuya clave está publicada (tiene dominios autorizados o se ha usado desde un navegador) no puede recibir permisos fuera de los del widget, y a una que los tiene no se le pueden añadir dominios. notAllowedScopes dice cuáles. Crea otra aplicación, sin dominios autorizados, para usar esos permisos desde tu servidor; quitar permisos o dominios se admite siempre, pero quitar los dominios no basta para conceder después un permiso de servidor: la clave estuvo en una página y hay que renovarla sin transición. Ver Claves dentro de una página web.
AUTH_TOKEN_INVALID
401 · Lo arregla quien programa · No se reintenta
No lo devuelve /api/external/v1: llega de las rutas de la aplicación (/api/...) cuando la cabecera Authorization no trae una sesión válida (falta, está mal formada o ha caducado). Si llamas con una clave de API de la organización, sus errores propios están en su tabla.
Plan y cuenta de la organización
MODULE_NOT_ENABLED
403 · Lo arregla la organización · No se reintenta
El plan de la organización no incluye el aplicativo que usa esta operación. El cuerpo trae moduleKey. No se arregla reintentando ni pidiendo permisos: lo resuelve el plan.
CAPABILITY_NOT_ENABLED
403 · Lo arregla la organización · No se reintenta
El plan de la organización no incluye la función que usa esta operación. El cuerpo trae capabilityKey.
FEATURE_COMING_SOON
403 · Lo arreglamos nosotros · No se reintenta
La función está en «Próximamente»: todavía no está disponible. No es un bloqueo de plan ni de permisos. Cuando esté disponible, la misma petición funcionará sin cambios.
TENANT_SUSPENDED
403 · Lo arregla la organización · No se reintenta
La cuenta de la organización está suspendida. Las consultas siguen funcionando; lo que crea o cambia datos se rechaza.
TENANT_CANCELLED
403 · Lo arregla la organización · No se reintenta
La cuenta de la organización está dada de baja. Como en la suspensión, las consultas siguen funcionando y las escrituras no.
TENANT_TERMINATION_READ_ONLY
403 · Lo arregla la organización · No se reintenta
La organización está cerrando su cuenta y solo admite consultas y exportaciones.
Datos de la petición
VALIDATION_ERROR
400 · Lo arregla quien programa · No se reintenta
Los datos no cumplen las reglas de la operación. El mensaje dice qué campo falla. Para encontrarlos todos de una vez, pasa el cuerpo por la comprobación de peticiones: devuelve cada error con la ruta del campo.
Los campos que la operación no declara no dan este error: se descartan y la respuesta lo dice en X-Utilia-Ignored-Fields. Las rectificativas son la excepción y rechazan cualquier campo fuera del contrato. Ver Dónde va cada parámetro.
Un campo obligatorio que no llega dice «Falta este campo obligatorio», nunca la regla de longitud o de formato que tenga después.
INVALID_JSON
400 · Lo arregla quien programa · No se reintenta
El cuerpo declara Content-Type: application/json, pero no se puede leer como JSON. El mensaje dice la línea y la columna donde falla y qué suele pasar ahí (comillas simples, una coma de más antes de cerrar, una llave sin cerrar); details trae position, line y column cuando se saben. Genera el cuerpo con el serializador de tu lenguaje (JSON.stringify, json.dumps) en vez de escribirlo a mano.
JSON_CONTENT_TYPE_REQUIRED
400 · Lo arregla quien programa · No se reintenta
La petición trae cuerpo, pero sin la cabecera Content-Type: application/json, así que el cuerpo no se ha leído y todos los campos aparecen como si faltaran. Pasa también con curl -d sin -H "Content-Type: application/json", que envía el JSON como formulario. Añade la cabecera; los SDK la ponen solos.
METHOD_NOT_ALLOWED
405 · Lo arregla quien programa · No se reintenta
La dirección existe, pero no con ese método. La cabecera Allow y el campo allowedMethods dicen con cuáles; por ejemplo, DELETE /external/v1/users responde que existe con GET. Si la dirección no existe con ningún método, la respuesta es 404.
REQUEST_BODY_TOO_LARGE
413 · Lo arregla quien programa · No se reintenta
El cuerpo pasa del tamaño máximo que se admite; details.limitBytes trae el tope. Los archivos no van dentro del JSON: súbelos por su ruta de subida y manda solo su identificador. «Comprobar una petición» tiene su propio tope, más pequeño.
Usuarios externos y tickets
USER_NOT_FOUND
404 · Lo arregla quien programa · No se reintenta
El usuario externo no existe. Dalo de alta antes con POST /external/v1/users/identify. Lo devuelven las rutas de tickets e IA.
EXTERNAL_USER_NOT_FOUND
404 · Lo arregla quien programa · No se reintenta
Lo mismo que USER_NOT_FOUND, en las rutas de facturación y métodos de pago. Trátalos igual.
TICKET_NOT_FOUND
404 · Lo arregla quien programa · No se reintenta
El ticket no existe o no es de este usuario.
TICKET_ACCESS_DENIED
403 · Lo arregla quien programa · No se reintenta
El usuario no tiene acceso a este ticket.
TICKET_CLOSED
403 · Lo arregla quien programa · No se reintenta
El ticket está cerrado y no admite mensajes nuevos. Reábrelo si su estado lo permite.
TICKET_CANNOT_REOPEN
404 · Lo arregla quien programa · No se reintenta
El ticket no existe o su estado no permite reabrirlo.
Archivos e IA
FILE_MISSING
400 · Lo arregla quien programa · No se reintenta
La petición no incluye ningún archivo.
FILE_INVALID_MIME
400 · Lo arregla quien programa · No se reintenta
Ese tipo de archivo no está permitido en la aplicación.
FILE_TOO_LARGE
400 o 413 · Lo arregla quien programa · No se reintenta
El archivo supera el tamaño máximo configurado en la aplicación.
FILE_TOO_MANY
400 · Lo arregla quien programa · No se reintenta
La subida trae más archivos de los que admite la operación.
FILE_INVALID_ATTACHMENTS
400 · Lo arregla quien programa · No se reintenta
Algún adjunto no es válido o no pertenece a la aplicación.
FILE_QUOTA_EXCEEDED
403 · Lo arregla la organización · No se reintenta
La aplicación ha agotado su espacio de almacenamiento.
FILE_NOT_FOUND
404 · Lo arregla quien programa · No se reintenta
El archivo no existe.
AI_NO_INPUT
400 · Lo arregla quien programa · No se reintenta
Hay que enviar texto, audio o imágenes.
AI_AUDIO_TOO_LARGE
400 · Lo arregla quien programa · No se reintenta
El audio es demasiado grande para la transcripción directa. Usa POST /external/v1/tickets/ai-transcribe-async.
EXTERNAL_AI_DISABLED
403 · Lo arregla la organización · No se reintenta
La organización tiene desactivada la IA para las aplicaciones externas.
AI_BUDGET_EXHAUSTED
403 · Lo arregla la organización · No se reintenta
Se ha agotado el saldo de IA disponible para esta operación.
Facturación de la aplicación
Para descubrir estos errores sin emitir nada, valida la factura antes: Probar la facturación sin emitir facturas.
BILLING_NOT_ENABLED
403 · Lo arregla la organización · No se reintenta
La facturación de la aplicación está desactivada. La activa un Super Administrador en Dinero › Facturación de la ficha de la aplicación, con un motivo. Mientras tanto, POST /external/v1/invoices/validate funciona y lo dice como bloqueo.
BILLING_AMOUNT_EXCEEDS_LIMIT
403 o 422 · Lo arregla la organización · No se reintenta
El importe supera el tope configurado para la facturación de la aplicación.
BILLING_IDEMPOTENCY_CONFLICT
409 · Lo arregla quien programa · No se reintenta
La clave de idempotencia ya se usó con otros datos. Una clave identifica una operación con su cuerpo: si cambias el cuerpo, es otra operación y necesita otra clave.
BILLING_CURRENCY_NOT_SUPPORTED
409 · Lo arregla quien programa · No se reintenta
Esa moneda no se admite en esta operación.
INVOICE_NOT_FOUND
404 · Lo arregla quien programa · No se reintenta
La factura no existe.
INVOICE_NOT_ACCESSIBLE
404 · Lo arregla quien programa · No se reintenta
La factura no existe o no es de esta aplicación. El mensaje es el mismo en los dos casos.
INVOICE_STATE_INVALID
409 · Lo arregla quien programa · No se reintenta
El estado de la factura no permite esta operación.
INVOICE_ALREADY_CANCELLED
409 · Lo arregla quien programa · No se reintenta
La factura ya está anulada.
INVOICE_ALREADY_PAID
409 · Lo arregla quien programa · No se reintenta
La factura ya está cobrada.
INVOICE_PDF_NOT_AVAILABLE
503 o 409 · Lo arreglamos nosotros · Se puede reintentar
El PDF de la factura todavía no está disponible. Con 503 y retryable: true, repite pasados retryAfterSeconds (15 si se está preparando, 120 si el almacén no responde). Con 409 y retryable: false, el PDF necesita que lo revise el equipo de la organización.
INVOICE_PDF_PENDING
409 · Lo arreglamos nosotros · Se puede reintentar
Al descargar el PDF de una factura emitida (GET /external/v1/invoices/:id/pdf): el PDF original todavía se está preparando. Repite la descarga en unos segundos.
INVOICE_PDF_REVIEW_REQUIRED
409 · Lo arregla la organización · No se reintenta
El PDF original de la factura no se puede verificar y el equipo de la organización tiene que revisarlo antes de descargarlo o enviarlo. Repetir no lo arregla.
INVOICE_PDF_STORAGE_UNAVAILABLE
503 · Lo arreglamos nosotros · Se puede reintentar
El almacén de documentos no ha respondido al pedir el PDF. Repite la descarga más tarde.
INVOICE_EMAIL_NOT_SENT
502 · Lo arreglamos nosotros · Se puede reintentar
La factura está emitida, pero el correo no ha salido. Con retryable: true el servidor de correo no responde; con retryable: false, el servidor de salida rechazó el envío. La factura no se vuelve a crear nunca: se reenvía.
INVOICE_EMAIL_NO_RECIPIENT
422 · Lo arregla quien programa · No se reintenta
No hay ninguna dirección a la que enviar la factura.
INVOICE_EMAIL_RECIPIENT_NOT_ALLOWED
422 · Lo arregla quien programa · No se reintenta
Un destinatario no es una dirección conocida de la factura.
INVOICE_PUBLIC_LINK_NOT_AVAILABLE
404 · Lo arregla quien programa · No se reintenta
La factura no tiene un enlace público disponible.
INVOICE_RECIPIENT_REQUIRED
400 · Lo arregla quien programa · No se reintenta
Una factura ordinaria necesita el bloque recipient. Para un consumidor sin datos, emite una simplificada.
INVOICE_RECIPIENT_INCOMPLETE
400 · Lo arregla quien programa · No se reintenta
Faltan datos del destinatario. missingFields dice cuáles.
SIMPLIFIED_INVOICE_AMOUNT_EXCEEDED
422 · Lo arregla quien programa · No se reintenta
Una factura simplificada no puede superar 400 € impuestos incluidos. Emite una ordinaria.
SIMPLIFIED_RECIPIENT_INCOMPLETE
400 · Lo arregla quien programa · No se reintenta
La simplificada trae el NIF del destinatario sin el resto de sus datos. missingFields dice cuáles.
TAX_INCLUSIVE_PRICE_NOT_REPRESENTABLE
422 · Lo arregla quien programa · No se reintenta
Con precios con impuestos incluidos, el importe de una línea no tiene base exacta al céntimo. lineNumber dice cuál (empieza en 1).
TAX_INCLUSIVE_GLOBAL_DISCOUNT_UNSUPPORTED
400 · Lo arregla quien programa · No se reintenta
Los precios con impuestos incluidos no admiten un descuento global.
TAX_SYSTEM_RESIDENCE_MISMATCH
400 · Lo arregla quien programa · No se reintenta
La residencia del destinatario no cuadra con el sistema fiscal de la factura.
IGIC_SMALL_BUSINESS_TAXED_LINE
400 · Lo arregla quien programa · No se reintenta
En el régimen del pequeño empresario del IGIC, las líneas no llevan cuota (tampoco IGIC_0). lineNumber dice cuál.
IGIC_SMALL_BUSINESS_REQUIRES_IGIC
400 · Lo arregla quien programa · No se reintenta
La exención del pequeño empresario solo vale en facturas con IGIC.
IGIC_SMALL_BUSINESS_NOT_ACTIVE
400 · Lo arregla la organización · No se reintenta
La fecha de la factura está fuera de los periodos del régimen del pequeño empresario que tiene configurados la organización.
INVOICE_SERIES_NOT_AVAILABLE
400 · Lo arregla quien programa · No se reintenta
La serie de seriesCode no existe o no es de esta aplicación. El mensaje es el mismo en los dos casos.
INVOICE_SERIES_TYPE_MISMATCH
400 · Lo arregla quien programa · No se reintenta
La serie es de otro tipo de documento (una de ordinarias para una simplificada, o al revés).
INVOICE_SERIES_INACTIVE
409 · Lo arregla la organización · No se reintenta
La serie de facturación está desactivada.
INVOICE_ISSUE_DATE_OUT_OF_ORDER
400 · Lo arregla quien programa · No se reintenta
issueDate es futura o anterior a la última factura de la serie. Trae issueDate y today, o lastIssueDate y seriesCode. No se numera nada.
INVOICE_NUMBERING_UNAVAILABLE
500 · Lo arreglamos nosotros · Se puede reintentar
La numeración no se pudo preparar y la emisión no llegó a empezar: no se reservó número ni se creó nada. Repetir la petición, con la misma clave de idempotencia, es seguro.
INVOICE_ISSUANCE_REVIEW_REQUIRED
500 · Lo arregla la organización · No se reintenta
La factura quedó emitida, pero su cierre fiscal no terminó y pasa a revisión del equipo de la organización. Repetir con la misma clave devuelve esa factura en revisión, nunca otra. No la emitas de nuevo con otra clave.
RECTIFICATION_NOT_ALLOWED
409 · Lo arregla quien programa · Según el cuerpo
La factura no admite una rectificación ahora; el mensaje dice por qué. Con retryable: true (la emisión o el PDF original siguen en curso) basta con repetirla pasados retryAfterSeconds. Ver Cuándo se puede rectificar.
RECTIFICATION_AMOUNT_EXCEEDS_REMAINING
409 · Lo arregla quien programa · No se reintenta
El importe supera lo que queda por rectificar. Trae remainingRectifiableAmount.
RECTIFICATION_AMOUNT_NOT_REPRESENTABLE
422 · Lo arregla quien programa · No se reintenta
El importe no se puede repartir al céntimo entre los tramos fiscales de la factura.
RECTIFICATION_HISTORY_REVIEW_REQUIRED
409 · Lo arregla la organización · No se reintenta
Las rectificaciones anteriores no cuadran y el equipo de la organización tiene que revisarlas antes de rectificar otra vez.
RECTIFICATION_OPERATION_INCOMPLETE
500 · Lo arreglamos nosotros · Según el cuerpo
La rectificación no terminó de registrarse por un fallo interno. Con retryable: true, repetirla con la misma clave de idempotencia la reanuda sin duplicar nada; con retryable: false, la operación necesita que la revise el equipo.
REFUND_NOT_ALLOWED
409 · Lo arregla quien programa · No se reintenta
Esta factura no admite un reembolso: no tiene cobros completados o el importe supera lo cobrado.
REFUND_EXCEEDS_COLLECTED
409 · Lo arregla quien programa · No se reintenta
La devolución supera lo cobrado fuera de la pasarela de UTILIA OS. Trae refundableAmount.
REFUND_REFERENCE_ALREADY_USED
409 · Lo arregla quien programa · No se reintenta
La referencia de la devolución ya figura en otro reembolso de la organización, también si lo registró a mano su equipo.
CLIENT_NOT_ACCESSIBLE
404 · Lo arregla quien programa · No se reintenta
El cliente no existe o no está al alcance de esta aplicación.
Cobros, métodos de pago y suscripciones
STRIPE_ACCOUNT_NOT_READY
409 · Lo arregla la organización · No se reintenta
La cuenta de cobros de la organización todavía no está lista para cobrar.
PAYMENT_METHOD_NOT_FOUND
404 · Lo arregla quien programa · No se reintenta
El método de pago no existe.
PAYMENT_METHOD_INACTIVE
409 · Lo arregla quien programa · No se reintenta
El método de pago ya no está activo.
PAYMENT_METHOD_OWNERSHIP
Lo arregla quien programa · No se reintenta
El método de pago es de otro usuario.
PAYMENT_METHOD_ACTIVE_INTENT
409 · Lo arregla quien programa · Se puede reintentar
El método de pago tiene un cobro en curso. Repite cuando termine.
PAYMENT_AUTHORIZATION_REQUIRED
409 · Lo arregla quien programa · No se reintenta
Para cobrar sin la persona delante hace falta su autorización de cobro. Pídesela con su consentimiento.
AUTO_CHARGE_DISABLED_FOR_ORGANIZATION
409 · Lo arregla la organización · No se reintenta
La organización tiene desactivado el cobro automático con tarjeta. No es lo mismo que la falta de autorización del usuario: recoger otro consentimiento no lo desbloquea.
PAYMENT_AUTHORIZATION_NOT_FOUND
404 · Lo arregla quien programa · No se reintenta
La autorización de cobro no existe, o es de otro usuario o de otra aplicación.
PAYMENT_AUTHORIZATION_NOT_ACTIVE
409 · Lo arregla quien programa · No se reintenta
La autorización ya no sirve para cobrar: fue revocada, se consumió o su tarjeta caducó.
PAYMENT_AUTHORIZATION_CONSENT_MISMATCH
422 · Lo arregla quien programa · No se reintenta
El texto o la versión del consentimiento no coinciden con el vigente. Vuelve a pedir el texto y muéstralo tal cual.
SUBSCRIPTION_NOT_ACCESSIBLE
404 · Lo arregla quien programa · No se reintenta
La suscripción no existe, no es de esta aplicación o no es de este usuario.
SUBSCRIPTION_STATE_INVALID
409 · Lo arregla quien programa · No se reintenta
El estado de la suscripción no permite esta operación: pausar una ya pausada, reanudar una cancelada o cambiar una terminada.
SCHEDULED_CHARGE_NOT_ACCESSIBLE
404 · Lo arregla quien programa · No se reintenta
El cobro programado no existe o no es de esta aplicación.
SCHEDULED_CHARGE_NOT_CANCELLABLE
409 · Lo arregla quien programa · No se reintenta
El cobro programado ya no se puede cancelar: su ventana se cerró o ya se está ejecutando.
SCHEDULED_CHARGE_RETRY_TOO_SOON
409 · Lo arregla quien programa · Se puede reintentar
Es pronto para reintentar este cobro: el motor admite 5 reintentos manuales cada 24 horas. Repetir en bucle no lo acelera.
CHARGE_FAILED
402 · Lo arregla quien programa · No se reintenta
La pasarela ha rechazado el cobro. El cuerpo trae failureCode y failureMessage.
CHARGE_REQUIRES_ACTION
409 · Lo arregla quien programa · No se reintenta
El banco exige que la persona confirme el cobro. No es un fallo de tu aplicación: lleva a tu usuario al enlace público de pago.
OUTBOUND_DOMAIN_NOT_ALLOWED
403 · Lo arregla la organización · No se reintenta
El destino no está en la lista de dominios salientes autorizados de la organización. Lo añade un administrador.
CRM, chat y presupuestos
CONTACT_NOT_FOUND
404 · Lo arregla quien programa · No se reintenta
El contacto no existe, es de otra organización o la aplicación no puede leerlo: un contacto dado de baja o inactivo responde igual si la aplicación no tiene crm:contacts:read:opted-out. El cuerpo es el mismo en los tres casos. Si esperabas encontrarlo, pide ese permiso a un administrador.
LEAD_NOT_FOUND
404 · Lo arregla quien programa · No se reintenta
El lead no existe.
CLIENT_NOT_FOUND
404 · Lo arregla quien programa · No se reintenta
El cliente no existe.
CONTACT_MERGED
409 · Lo arregla quien programa · No se reintenta
El contacto se fusionó con otro y no se ha escrito nada. Usa el identificador que indica la respuesta.
CLIENT_MERGED
409 · Lo arregla quien programa · No se reintenta
El cliente se fusionó con otro y no se ha escrito nada. Usa mergedIntoId, en la raíz de la respuesta.
LEAD_ALREADY_CONVERTED
409 · Lo arregla quien programa · No se reintenta
El lead ya está convertido.
LEAD_ALREADY_QUALIFIED
409 · Lo arregla quien programa · No se reintenta
El lead ya está cualificado.
LEAD_ALREADY_DISQUALIFIED
409 · Lo arregla quien programa · No se reintenta
El lead ya está descartado.
LEAD_ALREADY_LOST
409 · Lo arregla quien programa · No se reintenta
El lead ya está marcado como perdido.
LEAD_CONVERSION_REQUIRES_REASON
422 · Lo arregla quien programa · No se reintenta
Para convertir este lead hace falta un motivo (reason, de 20 caracteres como mínimo). Queda en el registro de auditoría.
LEAD_UPDATE_CONFLICT
409 · Lo arregla quien programa · No se reintenta
El lead ha cambiado desde que lo leíste. Vuelve a leerlo y repite con su updatedAt nuevo en expectedUpdatedAt.
CLIENT_UPDATE_CONFLICT
409 · Lo arregla quien programa · No se reintenta
El cliente ha cambiado desde que lo leíste. Vuelve a leerlo antes de guardar.
EXTERNAL_APP_CREATOR_MISSING
422 · Lo arregla la organización · No se reintenta
La aplicación no tiene una persona creadora válida en UTILIA OS, y la operación (como convertir un lead) la necesita.
CHANNEL_NOT_FOUND
404 · Lo arregla quien programa · No se reintenta
El canal no existe.
MESSAGE_NOT_FOUND
404 · Lo arregla quien programa · No se reintenta
El mensaje no existe.
APP_NOT_AUTHORIZED_IN_CHANNEL
403 · Lo arregla la organización · No se reintenta
La aplicación tiene el permiso de la API, pero no está autorizada en ese canal. El permiso autoriza la acción; el canal se concede aparte.
BUDGET_NOT_FOUND
404 · Lo arregla quien programa · No se reintenta
El presupuesto no existe. El mismo 404 si es de otra organización.
BUDGET_SIGNATURE_NOT_FOUND
404 · Lo arregla quien programa · No se reintenta
La firma no existe en ese presupuesto.
BUDGET_COMMENT_VISIBILITY_NOT_ALLOWED
403 · Lo arregla quien programa · No se reintenta
Por la API solo se escriben comentarios visibles para el cliente (CLIENT). Las notas internas del equipo nunca.
BUDGET_SIGNED_PDF_UNAVAILABLE
No es un error HTTP: llega en reason.errorCode de una verificación de firma con status: UNVERIFIABLE (respuesta 200). El PDF firmado ya no existe. No indica que el documento se haya alterado.
BUDGET_SIGNED_PDF_UNREADABLE
Como el anterior, pero el PDF existe y el almacén no lo ha devuelto. Puede ser pasajero: repite la verificación más tarde.
Instalaciones del catálogo
Los devuelven las rutas de /external/v1/app-installations, con la clave de la aplicación que publica una ficha en el catálogo. Cómo se canjea el código está en La instalación y el canje del código.
EXCHANGE_FROM_BROWSER
403 · Lo arregla quien programa · No se reintenta
El canje llegó con las cabeceras de un navegador (Origin o Sec-Fetch-Site). Las credenciales de una instalación solo se entregan a un servidor: haz el canje desde el tuyo, nunca desde la página a la que llega la persona.
INSTALLATION_CODE_WRONG_APP
403 · Lo arregla quien programa · No se reintenta
El código es de la ficha de otra aplicación de tu organización. Canjéalo con la clave de la aplicación que publicó esa ficha.
INSTALLATION_CODE_INVALID
404 · Lo arregla quien programa · No se reintenta
El código no existe para tu aplicación, o la instalación ya no se puede conectar porque está desinstalada o suspendida. No dice cuál de las dos cosas pasa. Comprueba que llegó entero; si sigue, pide a la empresa que vuelva a conectar desde Instaladas.
INSTALLATION_CODE_USED
409 · Lo arregla quien programa · No se reintenta
El código ya se canjeó y las credenciales no se entregan dos veces. Suele ser la misma dirección de instalación abierta dos veces: si ya guardaste las credenciales de esa installation_id, sigue adelante. Si las perdiste, pide a la empresa que vuelva a conectar.
INSTALLATION_CODE_EXPIRED
410 · Lo arregla la organización · No se reintenta
Pasaron los 30 minutos del código sin canjearlo, y la instalación está en Falta conectar. La empresa pulsa Conectar con tu aplicación en Instaladas y te llega un código nuevo.
APP_INSTALLATION_NOT_FOUND
404 · Lo arregla quien programa · No se reintenta
No hay ninguna instalación con ese identificador en la ficha de tu aplicación: no existe o es de otra aplicación. Usa el installation_id que recibiste en la dirección de instalación o en X-Utilia-Installation-Id.
Registro de errores de la aplicación
ERROR_STORAGE_UNAVAILABLE
503 · Lo arreglamos nosotros · Se puede reintentar
El registro de errores no ha podido guardar el error que mandaste a POST /errors/report. Llega con Retry-After: 30: repítelo pasados esos segundos. En un lote (POST /errors/batch) no hay 503: el error que no se guardó trae reason: storage_failed y se repite solo ese.
Que un error no se registre por los límites del registro (rate_limited, quota_exhausted, overloaded) o por ser un 4xx esperado (discarded_expected) no es un error HTTP: la respuesta es 201 con accepted: false y el motivo. Ver Enviar los errores de tu aplicación.
Pruebas y diagnóstico
Los devuelven las rutas de /external/v1/diagnostics. Cómo se usan está en Rutas del diagnóstico.
DIAGNOSTICS_RATE_LIMITED
429 · Lo arregla quien programa · Se puede reintentar
Has lanzado demasiadas pruebas seguidas: 6 pruebas activas por minuto y aplicación (en el panel, por persona), o 5 avisos de prueba por minuto y aplicación (un cupo compartido con el panel). Espera los segundos de Retry-After, que también van en retryAfterSeconds. Las cabeceras X-RateLimit-* de esta respuesta son las de ese cupo, con X-RateLimit-Remaining: 0, no las del freno general por minuto.
DIAGNOSTICS_UNAVAILABLE
503 · Lo arreglamos nosotros · Se puede reintentar
Ahora mismo no se pueden lanzar pruebas: el contador de su cupo no responde, y la prueba activa y los avisos de prueba no se lanzan sin contarlos. No dice nada de tu integración. Repite en unos minutos.
DIAGNOSTICS_NOT_AVAILABLE_FOR_PUBLISHABLE_KEY
403 · Lo arregla la organización · No se reintenta
La clave de la aplicación está publicada en páginas web (tiene dominios autorizados o se ha usado desde un navegador) y cualquiera puede leerla. Con ella no se lanzan las pruebas que enseñan su tráfico, leen como la aplicación o envían avisos a su servidor: las llamadas rechazadas, la prueba activa, la muestra de un aviso y la comprobación del receptor. Lánzalas desde la pestaña Pruebas de la aplicación en el panel. El diagnóstico, /me, check-request y el contrato siguen respondiendo con esa clave. Ver Claves publicadas en una web.
WEBHOOK_NO_URL
400 · Lo arregla la organización · No se reintenta
La aplicación no tiene dirección de avisos configurada.
WEBHOOK_URL_INVALID
400 · Lo arregla la organización · No se reintenta
La dirección de avisos no es válida o apunta a una red privada. Por seguridad, ni se guarda ni se entrega.
WEBHOOK_SECRET_NOT_CONFIGURED
409 · Lo arregla la organización · No se reintenta
La aplicación no tiene clave de firma de avisos, así que no se puede comprobar el receptor.
Estados HTTP sin código
Si la respuesta no trae errorCode, o trae uno que no está en esta página, docsUrl apunta aquí, a su estado.
HTTP 400
La petición no es válida. Lo arregla quien programa.
HTTP 401
La petición no trae una credencial válida. Lo arregla quien programa.
HTTP 403
La aplicación no tiene acceso a esta operación. Lo arregla la organización.
HTTP 404
La dirección o el recurso no existen. Lo arregla quien programa. Una ruta que no es de la API pública responde igual que una que no existe: compruébala con la comprobación de peticiones, que sugiere las parecidas.
HTTP 405
La operación no admite ese método HTTP. Lo arregla quien programa.
HTTP 408
La petición ha tardado demasiado en llegar. Se puede reintentar.
HTTP 409
La operación choca con el estado actual del recurso. Lo arregla quien programa: vuelve a leerlo antes de repetir.
HTTP 413
La petición es demasiado grande. Lo arregla quien programa.
HTTP 415
El formato del cuerpo no se admite. Envía Content-Type: application/json.
HTTP 422
Los datos tienen la forma correcta, pero no se pueden aplicar. Lo arregla quien programa.
HTTP 429
Se ha superado un límite de peticiones. Sin código es un freno por minuto: el general, el de facturas y cobros o el de los errores del navegador. Espera lo que diga Retry-After. Se puede reintentar. Las cifras están en Los límites de un vistazo.
HTTP 499
No es una respuesta que reciba tu programa: es como queda registrada, en las llamadas rechazadas y en el panel, una llamada que tu programa cortó antes de recibir la respuesta. Casi siempre, su tiempo de espera es más corto de lo que tarda la ruta. Lo arregla quien programa: alarga la espera y, si era una escritura, comprueba si se hizo antes de repetirla.
HTTP 500
Ha fallado algo de nuestro lado. Lo arreglamos nosotros y se puede reintentar. Si se repite, escríbenos con el requestId.
HTTP 502
Un servicio del que dependemos no ha respondido bien. Se puede reintentar.
HTTP 503
El servicio no está disponible en este momento. Se puede reintentar.
HTTP 504
Un servicio del que dependemos ha tardado demasiado. Se puede reintentar.
Otras familias de errores
Ventanilla única del IVA (Próximamente)
La ventanilla única del IVA está en «Próximamente». Cualquier dato suyo responde 403 FEATURE_COMING_SOON con featureKey: "finance.oss".
Gestión de aplicaciones desde el panel
No los devuelve la API externa, sino la API del panel con la que una persona gestiona las aplicaciones (/api/integrations/apps/...):
| errorCode | HTTP | Qué significa |
|---|---|---|
APP_SLUG_DUPLICATE | 409 | Ya existe una aplicación con ese identificador. |
EXTERNAL_APP_SLUG_HELD_BY_DELETED | 409 | El identificador lo conserva una aplicación eliminada. Restáurala o elimínala definitivamente para reutilizarlo. |
APP_NOT_FOUND | 404 | La aplicación no existe, es de otra organización o, según la operación, está eliminada. |
EXTERNAL_APP_HAS_ACTIVE_BILLING | 409 | No se puede eliminar: tiene suscripciones activas o en pausa o cobros programados pendientes. details dice cuántos. |
CONFIRMATION_MISMATCH | 400 | Para eliminarla definitivamente, confirmName tiene que ser el nombre exacto de la aplicación. |
EXTERNAL_APP_PERMANENT_DELETE_BLOCKED | 409 | Algo impide eliminarla definitivamente. details.blockers dice qué y cómo resolverlo. |
SCOPE_OUT_OF_PLAN | 400 | El permiso que intentas conceder exige algo que el plan no incluye. |
DELIVERY_NOT_FOUND | 404 | La entrega del aviso no existe. |
DELIVERY_ALREADY_SUCCESS | 400 | No se puede reintentar una entrega que ya llegó bien. |
Claves de API de la organización
No los devuelve la API externa, sino la API de la aplicación cuando la llamas con una clave de API de la organización (Authorization: Bearer utk_...). Qué hacer con cada uno está en su tabla de errores.
| errorCode | HTTP | Qué significa |
|---|---|---|
API_KEY_INVALID | 401 | La clave no existe o está mal copiada. |
API_KEY_REVOKED | 401 | La clave está revocada. |
API_KEY_EXPIRED | 401 | La clave ha caducado. |
API_KEY_UNAVAILABLE | 401 | No se ha podido comprobar la clave en ese momento. |
API_KEY_BROWSER_NOT_ALLOWED | 403 | La petición llegó desde un navegador: estas claves solo valen desde un servidor. |
API_KEY_RESPONSIBLE_INACTIVE | 403 | La persona responsable de la clave ya no está activa. |
API_KEY_ROUTE_NOT_AVAILABLE | 403 | Esa ruta no admite claves. |
API_KEY_STREAMING_NOT_AVAILABLE | 403 | Las conexiones de eventos en tiempo real no admiten claves. |
API_KEY_PERMISSION_NOT_GRANTED | 403 | La clave no incluye el permiso; permissions dice cuáles faltan. |
API_KEY_RESPONSIBLE_PERMISSION_MISSING | 403 | La persona responsable no tiene el permiso; permissions dice cuáles. |
API_KEY_ACTION_REQUIRES_SESSION | 403 | La acción pide la verificación en dos pasos de una persona. |
RATE_LIMIT_EXCEEDED | 429 | Cupo por hora de la clave agotado, o demasiadas claves no válidas desde tu IP. Llega con Retry-After. |