# Solución de problemas de solicitudes

Llamadas rechazadas, invitaciones que nunca llegaron, y callbacks que nunca aterrizaron.

## Solución de problemas de solicitudes

Dónde mirar cuando una solicitud fue rechazada, una invitación nunca llegó, o un flujo de trabajo sigue esperando un callback que ya ocurrió.

<h2 id="reading-errors">Leer un error</h2>

<p>
  Todo rechazo lleva dos cosas: un <code>code</code> para el tipo de fallo, y un <code>details.reason</code> para la causa concreta. Decide
  según el código; lee el motivo para saber qué arreglar. Cuando ayuda, <code>details</code> también nombra el <code>field</code> ofensor,
  las claves que se habrían aceptado, o las claves de opción que admite una pregunta de elección.
</p>

<p>
  Los métodos de solicitud usan cuatro códigos: <code>VALIDATION_ERROR</code> (la llamada estaba mal), <code>CONFLICT</code> (la solicitud
  está en el estado equivocado, o se reutilizó una clave de idempotencia), <code>NOT_FOUND</code>, y <code>UPGRADE_REQUIRED</code> (un
  límite de plan o la asignación mensual). Llamar demasiado rápido devuelve <code>RATE_LIMITED</code> en su lugar, con{' '}
  <code>retryAfterMs</code> — consulta <a href="/es/requests/creating-requests#rate-limit">el límite de frecuencia</a>.
</p>

```
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "No field with key \"company\".",
    "details": { "reason": "UNKNOWN_FIELD_KEY", "field": "prefill.company", "validKeys": ["company_name", "company_size"] }
  }
}
```

<h2 id="reasons">Motivos que puedes ver</h2>

<h3 id="reasons-setup">Hacer bien la llamada</h3>

<h3 id="reasons-state">Actuar sobre una solicitud existente</h3>

<h2 id="invitation-problems">La invitación nunca llegó</h2>

<p>Abre la solicitud en la página de Solicitudes y lee la cronología. La primera línea de invitación te dice en qué caso estás.</p>

> ℹ️ **No hay ninguna entrada en la cronología**
> <p>
>     Entonces nunca se pidió ningún correo. La solicitud se creó con <code>delivery: "none"</code> — entrega el enlace tú mismo, o crea una
>     nueva solicitud con <code>delivery: "email"</code>.
>   </p>

<p>
  Las invitaciones y los recordatorios comparten un cupo de diez correos al día por formulario y dirección de destinatario, y una solicitud
  nunca escribe a su destinatario más de nueve veces en toda su vida — una invitación y hasta ocho recordatorios.
</p>

<h2 id="callback-problems">El callback nunca aterrizó</h2>

<p>
  La sección <strong>Callback</strong> del panel de la solicitud muestra la URL y el resultado. <em>Callback fallido tras N intentos</em>{' '}
  significa que Formstep lo intentó y se rindió — ocho intentos a lo largo de unas cuatro horas.
</p>

<ol>
  <li>
    <strong>Comprueba la URL.</strong> Se muestra en el panel. La URL de reanudación de una herramienta de flujos de trabajo pertenece a una
    ejecución, y una ejecución que se borró o se recreó ya no responde en ella.
  </li>
  <li>
    <strong>Comprueba qué devolvió tu endpoint.</strong> Cualquier cosa fuera de 2xx es un fallo. Un 4xx que no sea 408 ni 429 detiene los
    reintentos de inmediato — Formstep lo interpreta como "tu endpoint rechazó esto", y reenviar los mismos bytes no puede cambiarlo.
  </li>
  <li>
    <strong>Arregla el receptor y luego pulsa Reproducir.</strong> El mismo payload sale de nuevo con el mismo id de evento, así que un
    receptor que desduplica está a salvo.
  </li>
</ol>

> ⚠️ **¿Falla la comprobación de la firma?**
> <p>
>     Casi siempre es el cuerpo bruto. Si analizas el JSON y lo reserializas antes de hashearlo, los bytes difieren y la firma nunca
>     coincidirá. Aplica el hash al cuerpo exactamente como llegó. La otra causa habitual es un secreto de firma regenerado que el receptor
>     aún no ha recogido — no hay periodo de gracia.
>   </p>

<h2 id="other">Otras cosas con las que te puedes topar</h2>

<ul>
  <li>
    <strong>El destinatario dice que el enlace muestra un aviso, no el formulario.</strong> La solicitud está en un estado final —
    completada, expirada o cancelada. Esa es la página de resultado. Crea una nueva solicitud si necesitan otro intento.
  </li>
  <li>
    <strong>Una automatización dejó de coincidir después de una edición</strong> — una respuesta desapareció del callback, o{' '}
    <code>requests.create</code> empezó a rechazar una clave con <code>UNKNOWN_FIELD_KEY</code>. Una clave de campo publicada desapareció:
    alguien la reescribió, o eliminó la pregunta y añadió una nueva en su lugar. Cambiar el título es seguro; ninguna de esas dos cosas lo
    es. Escribe la clave antigua en el campo (icono de claves de la barra de herramientas → <strong>Claves</strong>) y vuelve a publicar.
    Publicar avisa antes de que esto ocurra — consulta{' '}
    <a href="/es/requests/field-keys#removed-keys">Cuando una clave publicada está a punto de desaparecer</a>.
  </li>
  <li>
    <strong>El precompletado de una subida de archivo o una firma se rechaza.</strong> Eso no puede suministrarlo quien llama —{' '}
    <code>fields.list</code> los marca <code>prefillable: false</code>.
  </li>
  <li>
    <strong>Aparecieron dos solicitudes para una misma ejecución de flujo.</strong> La ejecución se reintentó sin un{' '}
    <code>idempotencyKey</code>. Pasa el id de ejecución como clave.
  </li>
</ul>

<div class="not-prose grid gap-3 sm:grid-cols-2">
  - [Callbacks y firma](/es/requests/callbacks) — Reintentos, reproducción y cómo verificar.
  - [La página de Solicitudes](/es/requests/managing-requests) — Dónde viven la cronología y las acciones.
</div>