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. nameno se compara: un reintento que solo cambianamedevuelve la ejecución existente, que conserva su primer nombre.
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.