Convenções
Ids, carimbos de data/hora, formato de erro, versionamento e tentativas.
| Convenção | Regra |
|---|---|
| IDs | UUIDs, opacos. Armazene-os inteiros; nunca faça parse nem encurte um |
| Carimbos de data e hora | RFC 3339 em UTC, por ex. 2026-09-22T04:10:00Z |
| Campos desconhecidos | ignore-os. Novos campos de resposta e novos valores de status podem chegar sem um incremento de versão |
| Versionamento | o prefixo carrega a versão principal. Uma mudança incompatível recebe um novo prefixo e aviso prévio |
| Erros | {"description": "…", "error": {"error_code": "…", "error_attributes": {…}}} — faça branch com base em error.error_code, registre descrição, nunca faça correspondência pelo texto. Veja Erros e limites |
| Tentativas | respeite Retry-After no 429. Nos 5xx, tente novamente com backoff exponencial e jitter |
Idempotência
Envie uma idempotency_key em toda execução que você iniciar. Ela é sua própria string — um número de episódio, um ID de job, qualquer coisa estável para essa unidade de trabalho.
- A mesma chave com o mesmo corpo retorna a execução que já existe, em vez de iniciar uma segunda.
- A mesma chave com um corpo diferente é recusado com
idempotency_conflict. Use uma nova chave para um novo trabalho.
Isso torna segura uma nova tentativa após um timeout, o que faz a diferença entre uma execução e uma duplicata pela qual você seria cobrado.
Rastreamento
Toda resposta traz x-morphic-trace-id. Registre-o. Quando você reporta um problema, esse ID é o que nos permite encontrar a execução em segundos, em vez de pedir uma janela de tempo.