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

La taxonomía completa: 62 códigos, congelada y append-only. Cada fila tiene id="<CODE>" para que el type URI ancle aquí.

Activo significa que la API lo emite hoy. Reservado (18 de 62) significa que el código forma parte del contrato pero ninguna ruta lo devuelve todavía: o el caso lo cubre otro código (un JSON malformado sale como VALIDATION_ERROR, no como MALFORMED_JSON), o espera una capacidad que aún no lanzamos (los TOKEN_* esperan OAuth), o la política de seguridad lo colapsa a propósito (cruzar de ambiente responde 404, no ENVIRONMENT_MISMATCH, para no confirmar que el recurso existe).

No programes una rama para un código reservado — sería código muerto. Un reservado nunca cambia de nombre ni de significado al activarse, así que agregarlo después es seguro; anticiparlo, no.

Código	Status	Título	Estado
`API_KEY_EXPIRED`	401	Unauthorized	Activo
`API_KEY_INVALID`	401	Unauthorized	Reservado
`API_KEY_REVOKED`	401	Unauthorized	Reservado
`AUTHENTICATION_REQUIRED`	401	Authentication required	Activo
`BATCH_NOT_FOUND`	404	Bulk-send batch not found	Activo
`CONSTANCIA_NOT_FOUND`	404	Constancia not found	Activo
`CONTRACT_REQUIRED`	403	NOM-151 contract required	Activo
`DEV_FEATURE_RESTRICTED`	403	Feature restricted in this environment	Activo
`DOCUMENT_ALREADY_SIGNED`	409	Document already signed	Activo
`DOCUMENT_ALREADY_VOIDED`	409	Conflict	Reservado
`DOCUMENT_CONFLICT`	409	Document conflict	Activo
`DOCUMENT_HAS_NO_FIELDS`	422	Unprocessable Entity	Reservado
`DOCUMENT_NOT_FOUND`	404	Document not found	Activo
`DOCUMENT_NOT_SENDABLE`	409	Document not sendable	Activo
`DOCUMENT_TOO_LARGE`	413	Document too large	Activo
`DUPLICATE_SIGNER`	422	Unprocessable Entity	Reservado
`ENVIRONMENT_MISMATCH`	403	Forbidden	Reservado
`EVENT_NOT_FOUND`	404	Not Found	Reservado
`EXPAND_DEPTH_EXCEEDED`	400	Expand depth exceeded	Activo
`EXTERNAL_ID_CONFLICT`	409	External id already used	Activo
`FOLDER_NOT_EMPTY`	409	Conflict	Activo
`FOLDER_NOT_FOUND`	404	Folder not found	Activo
`IDEMPOTENCY_KEY_IN_PROGRESS`	409	Idempotency key in progress	Activo
`IDEMPOTENCY_KEY_INVALID`	400	Idempotency key invalid	Activo
`IDEMPOTENCY_KEY_REQUIRED`	400	Idempotency key required	Activo
`IDEMPOTENCY_KEY_REUSED`	409	Idempotency key reused	Activo
`INSUFFICIENT_CREDITS`	402	Insufficient credits	Activo
`INSUFFICIENT_SCOPE`	403	Forbidden	Activo
`INTERNAL_ERROR`	500	Internal server error	Activo
`INVALID_CURSOR`	400	Invalid cursor	Activo
`INVALID_EXPAND`	400	Invalid expand path	Activo
`INVALID_FILTER`	400	Bad Request	Reservado
`INVALID_ID`	400	Malformed identifier	Activo
`INVALID_SORT`	400	Bad Request	Reservado
`INVALID_STATE_TRANSITION`	409	Conflict	Activo
`IP_NOT_ALLOWED`	403	IP address not allowed	Activo
`LIMIT_OUT_OF_RANGE`	400	Bad Request	Reservado
`MALFORMED_JSON`	400	Bad Request	Reservado
`METHOD_NOT_ALLOWED`	405	Method Not Allowed	Activo
`NOT_ACCEPTABLE`	406	Not Acceptable	Activo
`OAUTH_NOT_ENABLED`	401	Unauthorized	Reservado
`OAUTH_NOT_IMPLEMENTED`	501	Not Implemented	Activo
`PAYLOAD_TOO_LARGE`	413	Request Entity Too Large	Reservado
`PERMISSION_DENIED`	403	Permission denied	Activo
`QUOTA_EXCEEDED`	429	Too Many Requests	Reservado
`RATE_LIMITED`	429	Rate limited	Activo
`RESOURCE_NOT_FOUND`	404	Resource not found	Activo
`SEGURIDATA_UNAVAILABLE`	503	Constancia provider unavailable	Activo
`SERVICE_UNAVAILABLE`	503	Service Unavailable	Activo
`SIGNER_INVALID`	422	Unprocessable Entity	Reservado
`SIGNER_NOT_FOUND`	404	Not Found	Activo
`TEMPLATE_NOT_FOUND`	404	Template not found	Activo
`TOKEN_AUDIENCE_MISMATCH`	403	Forbidden	Reservado
`TOKEN_EXPIRED`	401	Unauthorized	Reservado
`TOKEN_INVALID`	401	Unauthorized	Reservado
`UNKNOWN_EVENT_TYPE`	422	Unknown event type	Activo
`UNSUPPORTED_API_VERSION`	400	Unsupported API version	Activo
`UNSUPPORTED_MEDIA_TYPE`	415	Unsupported Media Type	Activo
`VALIDATION_ERROR`	422	Validation failed	Activo
`WEBHOOK_LIMIT_EXCEEDED`	409	Conflict	Activo
`WEBHOOK_NOT_FOUND`	404	Webhook endpoint not found	Activo
`WEBHOOK_URL_INVALID`	422	Webhook URL invalid	Activo

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.