Funcionamento

Publicar com IA sem duplicar projetos

Antes de criar, consulte GET /projects e GET /subscription. Identifique o projeto solicitado por projectId ou slug exato e preserve esse ID durante todo o trabalho. Na criação, envie um slug estável escolhido para esse projeto. 409 com error.details.reason=PROJECT_ALREADY_EXISTS devolve projectId e slug da mesma organização: confira se é o projeto pretendido e reutilize-o. Não invente outro nome ou sufixo para contornar conflito ou cota.

Em POST /projects e POST /projects/<id>/deployments, envie Idempotency-Key: um identificador de 8–128 caracteres [A-Za-z0-9._:-]. Guarde uma chave para criar o projeto e outra para cada revisão de código. Repita a MESMA chave e o MESMO corpo se a resposta se perder; por 24 horas o sucesso é devolvido sem executar de novo. Corpo diferente com a mesma chave retorna 409 IDEMPOTENCY_KEY_REUSED. IDEMPOTENCY_PENDING ou IDEMPOTENCY_PREVIOUS_FAILURE exigem consultar projetos e histórico de deployments antes de agir: não gere outra chave às cegas. Uma correção real do código usa novo ZIP, novo sourceObjectKey e nova chave de deploy, mantendo projectId.

Não confunda o estado geral do projeto com a publicação atual: consulte GET /deployments/<id>. Enquanto estiver QUEUED, BUILDING ou HEALTHCHECK, acompanhe o mesmo deployment; em prazo excedido, informe a etapa pendente. Em FAILED, leia /diagnostico (texto), /logs?from=tail e runtime-logs; corrija build, porta, comando ou dependências e publique no MESMO projeto. Não crie outro projeto para resolver erro 500, 502, timeout ou fila. READY ainda exige verificar o HTTPS e o fluxo solicitado, como login, antes de anunciar sucesso funcional.

Antes de provisionar, consulte GET /databases e GET /projects/<id>/storage e reutilize os recursos do projeto. Banco e S3 são recursos associados, não projetos novos. Use connectionEnvKey, DATABASE_URL/REDIS_URL e as envKeys S3 retornadas; nunca derive senha ou host pelo país. O storage padrão é reutilizado; additional=true solicita outro vínculo e só deve ser usado quando o cliente pedir. Não coloque credenciais do banco ou S3 no navegador.

Use data.effectiveLimits, data.usage, data.executionAllowed e data.subscription de GET /subscription. Não deduza permissões só pelo nome Hobby/Pro/Enterprise. 402 PLAN_LIMIT_EXCEEDED não autoriza apagar recursos para liberar cota nem contratar extras. Réplicas desejadas não comprovam instâncias saudáveis: consulte /replicas e /metrics. Autoescala e cópias pagas precisam caber nos limites e ter autorização do cliente; a existência de uma região não comprova failover de banco, Redis ou arquivos.