Errores

Todas las respuestas de error tienen la misma forma. Lee error.code: es un valor estable y legible por máquina. El message es para personas y puede cambiar en cualquier momento, así que nunca ramifiques según el texto del mensaje.

{
  "error": {
    "code": "unknown_signer_role",
    "message": "One or more recipient roles do not match this template.",
    "details": { },
    "reference": "0190f3a2-7b6c-7e21-9a3f-2c9b1d4e5f60"
  }
}

details

Solo aparece cuando hay algo útil que decir. Dos casos merecen tratamiento explícito:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key is missing the required scope \"envelopes:send\".",
    "details": { "required_scope": "envelopes:send", "granted_scopes": ["templates:read"] }
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Slow down and retry after the indicated interval.",
    "details": { "retry_after": "15 minutes" }
  }
}

reference

Un UUID que identifica la entrada de log del servidor para ese fallo. Aparece en los errores que persistimos (5xx y 422) y no está en los errores de autenticación o validación que no generan log en el servidor.

Guárdalo en tus logs. Cuando nos reportes un problema, citar el reference nos permite encontrar el fallo exacto con una sola consulta en lugar de pedirte que lo reproduzcas.

Códigos de error

Cómo resolver sender_fields_incomplete

Este sorprende, porque la petición es perfectamente válida. Significa que la plantilla tiene campos asignados a su propio rol de remitente ("Me") que son obligatorios y están vacíos, así que no hay un documento completo que enviar.

La API rellena los campos del remitente automáticamente con lo que esté guardado en la plantilla; no puede inventar valores. Arréglalo en la plantilla, no en tu petición:

• da un valor a esos campos del remitente en la plantilla,
• márcalos como opcionales, o
• elimínalos.

Después repite la misma llamada.

Cómo gestionar bien los errores

• Ramifica según error.code, nunca según message.
• Reintenta 5xx, 429 y errores de red con espera progresiva, respetando la cabecera Retry-After en un 429. No reintentes los demás 4xx: la petición nos llegó y fue rechazada; corrige la petición.
• Renueva ante 401 invalid_token intercambiando tu clave por un token nuevo y reintenta una vez. Si recibes key_revoked, la clave se revocó: carga la clave de reemplazo en lugar de reintentar.
• Trata quota_exceeded como una señal del plan, no como un error transitorio: se resuelve cuando el periodo se reinicia o se mejora tu plan. Reintentar no sirve y, al enviar, significa que no se entregó nada.
• send_failed significa que no salió nada. El sobre se elimina, así que un reintento crea uno nuevo en lugar de duplicar una entrega.
• Registra reference siempre que esté presente.