Convenciones
Ids, marcas de tiempo, forma del error, versionado y reintentos.
| Convención | Regla |
|---|---|
| IDs | UUIDs, opacos. Almacénelos íntegros; nunca analice ni acorte uno |
| Marcas de tiempo | RFC 3339 en UTC, p. ej. 2026-09-22T04:10:00Z |
| Campos desconocidos | ignórelos. Pueden llegar nuevos campos de respuesta y nuevos valores de estado sin un cambio de versión |
| Versionado | el prefijo lleva la versión principal. Un cambio que rompa compatibilidad obtiene un nuevo prefijo y aviso previo |
| Errores | {"description": "…", "error": {"error_code": "…", "error_attributes": {…}}} — ramifique según error.error_code, registre description, nunca coincida en función de su texto. Véase Errores y límites |
| Reintentos | respete Retry-After en 429. En 5xx, vuelva a intentarlo con retroceso exponencial y jitter |
Idempotencia
Envíe un idempotency_key en cada ejecución que inicie. Es su propia cadena — un número de episodio, un id de trabajo, cualquier cosa estable para esa unidad de trabajo.
- La misma clave con el mismo cuerpo devuelve la ejecución que ya existe, en lugar de iniciar una segunda.
- La misma clave con un cuerpo diferente se rechaza con
idempotency_conflict. Use una nueva clave para trabajo nuevo.
Eso hace que reintentar tras un tiempo de espera sea seguro, que es la diferencia entre una sola ejecución y un duplicado por el que se le cobra.
Trazabilidad
Toda respuesta lleva x-morphic-trace-id. Regístrelo. Cuando informe de un problema, ese id es lo que nos permite encontrar la ejecución en segundos en lugar de pedirle una ventana de tiempo.