Base de conocimiento de GetMyBot

Errores de la API

Cómo interpretar un error, cuándo corregir la solicitud y cuándo repetirla. Reintentos de pagos y envíos sin crear duplicados.

En esta página

Si una solicitud falla, mira primero el código HTTP: por ejemplo, 401 señala un problema de acceso y 429 indica que has enviado solicitudes demasiado rápido. El campo error de la respuesta concreta el motivo. Una respuesta correcta contiene los datos directamente, sin un envoltorio común adicional.

Formato de error

En caso de error, el servidor devuelve un objeto JSON con un solo campo error y un mensaje:

{"error":"reaction not found"}

Usa el código de estado HTTP como señal principal. El texto de error sirve para los registros y para explicar el problema a quien usa tu integración.

Códigos de estado

Código HTTPQué significa
200 OKLa solicitud se ha completado y el cuerpo contiene datos.
201 CreatedSe ha creado un recurso nuevo; lo usan algunos endpoints POST.
204 No ContentLa operación se ha completado sin cuerpo de respuesta; lo usan algunas eliminaciones.
400 Bad RequestEl cuerpo o los parámetros de la solicitud son incorrectos.
401 UnauthorizedFalta el token, no es válido o ha caducado; también puede indicar que la ruta no admite tokens personales.
402 Payment RequiredEl plan o la cuota impiden la operación; por ejemplo, el almacenamiento propio de medios requiere una función premium.
403 ForbiddenAl token le falta el permiso necesario para esta ruta o su propietario carece de un derecho del panel (missing cabinet right; consulta El panel asociado al token).
404 Not FoundEl recurso no existe o no te pertenece.
409 ConflictHay un conflicto de estado, como un valor único duplicado. También puede indicar que una solicitud con el mismo Idempotency-Key aún se está ejecutando; consulta más abajo.
413 Payload Too LargeEl cuerpo supera el tamaño permitido (consulta Límites y tamaños). Las solicitudes con Idempotency-Key tienen un límite independiente y más bajo: 64 KiB.
422 Unprocessable EntityEl cuerpo tiene sintaxis válida, pero incumple una regla del producto. También puede indicar que ya se usó el mismo Idempotency-Key con otro cuerpo.
429 Too Many RequestsSe ha superado el límite de solicitudes (consulta Límites y tamaños).
500 Internal Server ErrorSe ha producido un error interno del servidor; vuelve a intentarlo más tarde.

Cómo tratar los errores

Considera correctos los códigos 2xx. Ante 401 o 403, comprueba el token, sus permisos y los derechos de su propietario en el panel. Ante 429 y 5xx, puedes reintentar con una espera que aumente progresivamente, llamada retroceso exponencial.

En general, repetir un 4xx distinto de 429 sin cambiar la solicitud no ayuda: corrige primero el problema. Hay una excepción importante: un 409 en una solicitud con Idempotency-Key puede significar que la misma operación sigue en curso. No la marques como fallida: un pago o envío podría estar realizándose en ese momento. Espera el tiempo indicado en Retry-After y repite con la misma clave.

Repetir operaciones de pago y envío: Idempotency-Key

La clave debe ser un UUID canónico, en minúsculas y con guiones, por ejemplo 9b1f0d4c-2f6a-4a5f-9a3f-1f2f3a4b5c6d. El mismo valor en otro formato se rechaza con 400.

Dónde funciona

El encabezado es opcional, pero se aplica en operaciones cuyo reintento puede costar dinero o iniciar un envío masivo:

  • POST /api/billing/topup: recargar el saldo;
  • POST /api/billing/subscribe: contratar una suscripción;
  • POST /api/bots/{botID}/reactions/{reactionID}/broadcast: iniciar una difusión.

En estas dos operaciones de envío de un operador es obligatorio; sin él, el servidor devuelve 400:

  • POST /api/bots/{botID}/users/{userID}/dialog/messages;
  • POST /api/bots/{botID}/support/dialogs/{subscriberID}/templates.

En las demás rutas, el encabezado se ignora. No lo trates como protección universal contra duplicados: fuera de esta lista, un reintento es otra solicitud.

Qué devuelve el servidor

  • Misma clave y mismo cuerpo, operación terminada: devuelve la respuesta guardada del primer intento, con el mismo código y cuerpo y con el encabezado Idempotent-Replay: true. La operación se realiza una sola vez. El registro dura una semana.
  • Misma clave, operación todavía en curso: devuelve 409 y Retry-After. Espera el tiempo indicado y repite con la misma clave. Una clave nueva podría crear un segundo cargo.
  • Misma clave, cuerpo diferente: devuelve 422. El servidor no puede saber cuál de los dos cuerpos querías enviar. Usa una clave nueva para la operación distinta.
  • Cuerpo de más de 64 KiB: devuelve 413. Estas operaciones requieren cuerpos pequeños; ese tamaño indica un error en el cliente.

Algunas respuestas no se guardan para la clave: 5xx, 408, 425 y 429. Indican que la solicitud no se completó. Repetirla con la misma clave permite volver a intentar la operación. Si se guardaran esas respuestas, recibirías el mismo rechazo en cada intento posterior durante una semana.

Cómo usar la clave

  1. Genera el UUID antes del primer intento y guárdalo con la tarea.
  2. Envía la solicitud con esa clave.
  3. Si se corta la conexión, hay un tiempo de espera, o recibes 5xx o 429, repite con la misma clave.
  4. Si recibes 409, espera el tiempo indicado en Retry-After y repite con la misma clave.
  5. Usa una clave nueva solo para otra operación.

El error habitual es generar una clave nueva en cada intento. En ese caso, el encabezado parece estar configurado, pero cada intento será una operación distinta para el servidor.

Errores de IA y configuración de escenarios

Managed AI devuelve códigos de motivo: not_available (función no disponible), not_entitled (sin acceso), budget_exceeded (presupuesto agotado), rate_limited (demasiadas solicitudes), provider_unavailable (servicio del modelo no disponible) y schema_validation_failed (la respuesta no cumple el formato exigido). Reintenta solo los errores cuya respuesta permita repetir la solicitud y conserva el mismo Idempotency-Key. Ante un 4xx distinto de 429 o un fallo de validación del esquema, corrige la solicitud: cambiar de proveedor del modelo no resolverá ese error.

Si Copilot devuelve stale_base, el cambio propuesto para la reacción se basó en una versión antigua: créalo de nuevo a partir de la estructura actual. Una modificación de las reglas de análisis devuelve 409 si otra solicitud ya las cambió. El recálculo de análisis y la reproducción de una ejecución se procesan como tareas de tamaño limitado; comprueba el estado de la tarea iniciada antes de lanzar otra. La comprobación de la conexión de Meta devuelve un código de motivo para localizar el problema. El error no incluye el cuerpo de respuesta de Meta ni el token de acceso.

Qué sigue