Errores de la API v3

Toda respuesta no-2xx es un documento RFC 9457 application/problem+json. Los clientes programan contra code (estable, append-only), nunca contra detail (inglés técnico, puede cambiar).

Estructura del error

Shape plano (sin envoltorio): 5 miembros core de RFC 9457 + extensiones de AllSign.

{
  "type": "https://developers.allsign.io/errors#DOCUMENT_NOT_FOUND",
  "title": "Document not found",
  "status": 404,
  "detail": "No document exists with id doc_...",
  "instance": "/v3/documents/doc_...",
  "code": "DOCUMENT_NOT_FOUND",
  "requestId": "req_...",
  "errors": []
}

Extensiones por código

Algunos códigos agregan campos: DOCUMENT_NOT_SENDABLE trae reason; PERMISSION_DENIED trae requiredScope y yourScopes; RATE_LIMITED viaja con el header Retry-After. Cada type enlaza al ancla de su código en esta página.

Errores a nivel de campo

La validación semántica (422 VALIDATION_ERROR) puebla errors[] con un objeto por campo: field (dot/bracket), pointer (JSON Pointer), code y detail.

"errors": [
  { "field": "signers[0].email", "pointer": "/signers/0/email",
    "code": "invalid_email", "detail": "not a valid email address" }
]

Catálogo de códigos

29 códigos, generados del contrato (openapi/v3.json → app/api/v3/error_codes.py). Cada fila tiene id="<CODE>" para que el type URI ancle aquí.

Código	Status	Título
`AUTHENTICATION_REQUIRED`	401	Authentication required
`BATCH_NOT_FOUND`	404	Bulk-send batch not found
`DEV_FEATURE_RESTRICTED`	403	Feature restricted in this environment
`DOCUMENT_ALREADY_SIGNED`	409	Document already signed
`DOCUMENT_CONFLICT`	409	Document conflict
`DOCUMENT_NOT_FOUND`	404	Document not found
`DOCUMENT_NOT_SENDABLE`	409	Document not sendable
`DOCUMENT_TOO_LARGE`	413	Document too large
`EXPAND_DEPTH_EXCEEDED`	400	Expand depth exceeded
`FOLDER_NOT_FOUND`	404	Folder not found
`IDEMPOTENCY_KEY_IN_PROGRESS`	409	Idempotency key in progress
`IDEMPOTENCY_KEY_INVALID`	400	Idempotency key invalid
`IDEMPOTENCY_KEY_REQUIRED`	400	Idempotency key required
`IDEMPOTENCY_KEY_REUSED`	409	Idempotency key reused
`INSUFFICIENT_CREDITS`	402	Insufficient credits
`INVALID_CURSOR`	400	Invalid cursor
`INVALID_EXPAND`	400	Invalid expand path
`INVALID_ID`	400	Malformed identifier
`INVALID_STATE_TRANSITION`	409	Conflict
`IP_NOT_ALLOWED`	403	IP address not allowed
`PERMISSION_DENIED`	403	Permission denied
`RATE_LIMITED`	429	Rate limited
`RESOURCE_NOT_FOUND`	404	Resource not found
`SIGNER_NOT_FOUND`	404	Not Found
`TEMPLATE_NOT_FOUND`	404	Template not found
`UNKNOWN_EVENT_TYPE`	422	Unknown event type
`VALIDATION_ERROR`	422	Validation failed
`WEBHOOK_NOT_FOUND`	404	Webhook endpoint not found
`WEBHOOK_URL_INVALID`	422	Webhook URL invalid

Correlación con AllSign-Request-Id

Cada respuesta trae el header AllSign-Request-Id: req_… y lo repite en requestId dentro del cuerpo del error. Cítalo al reportar un problema — es la llave para rastrear la petición en nuestros logs.