# Convenções da API

- **Base URL**: `https://api.nebularws.com`; todas as rotas ficam em `/v1`.
- **Autenticação**: `Authorization: Bearer nbk_…`, nunca em query string. Cookies são ignorados. Veja [Token de API](/comecar/token/).
- **Erros**: sempre `{"error": "<codigo>", "message": "..."}`. Trate pelo `error` (estável); mostre o `message` (pt-BR) a pessoas. Veja a [tabela de erros](/erros/tabela/).
- **404 anti-IDOR**: recurso inexistente e recurso de outro time/projeto respondem igual (`404 not_found`). `401` é genérico de propósito. `403` só aparece quando o recurso é seu e falta escopo. Não tente distinguir.
- **Paginação por cursor**: listas devolvem `items`, `next_cursor` e `has_more`. Siga `next_cursor` enquanto `has_more` for `true`; o cursor é opaco. Receita em [Galerias e arquivos](/cdn/galerias/#d-listar-com-cursor-next_cursor--has_more).
- **Idempotência**: todo `POST` que cria ou dispara aceita `Idempotency-Key` (8 a 128 caracteres `[A-Za-z0-9._:-]`). Mesma chave e mesmo pedido em 24 h devolve a mesma resposta (cabeçalho `Idempotent-Replay: true`); mesma chave com outro pedido dá `422 idempotency_conflict` (`409` no upload de galeria); chave malformada (fora de 8 a 128 caracteres `[A-Za-z0-9._:-]`), `400 invalid_request`. Só respostas `2xx` são gravadas. Veja [Galerias e arquivos](/cdn/galerias/#idempotência-idempotency-key).
- **Corpo JSON**: todo `POST`/`PUT`/`PATCH` **com corpo** leva `Content-Type: application/json`. Regra exata para `POST /v1/projects/{p}/deploy`, `POST .../services/{s}/deployments` e `POST .../deployments/{d}/rollback`: o corpo é **opcional**. Sem corpo (ou `Content-Length: 0`), com ou sem `Content-Type`, vale `{}`; com corpo, ele tem de ser JSON com `Content-Type: application/json` (outro tipo, como `text/plain` ou formulário, dá `415 unsupported_media_type`); o deploy de serviço aceita também `multipart/form-data` (campo `file`). Os exemplos mandam `Content-Type: application/json` e `{}` por ser a forma que funciona em qualquer cliente HTTP. Todo projeto nasce com um serviço `web` padrão, **público** e com `slug` ([Conceitos](/comecar/conceitos/#o-serviço-web-padrão)).
- **Rate limit**: por token e por IP; em `429` espere `Retry-After` segundos. Veja [Rate limit e retry](/erros/rate-limit-e-retry/).
- **Ids**: opacos. Projetos, serviços, deploys, bancos e demais recursos da v13 usam ULID em minúsculas de 26 caracteres (por exemplo `01m4kxaxjts58n5esjajbr5pg0`); galerias e arquivos têm prefixo do tipo (`gal_…`, `ast_…`, `ver_…`). Não os interprete nem dependa do formato: use o que a API devolveu.
- **Datas**: RFC 3339 em UTC (`2026-10-09T14:03:11Z`).
- **Assíncrono**: deploys, backups e restores respondem logo e terminam depois; consulte o recurso com backoff. Não há webhooks neste ciclo.
- **Estados de deploy**: `queued`, `building`, `deploying`, `ready`, `failed`, `blocked`, `canceled`, `superseded`. Terminais: todos menos `queued`, `building` e `deploying`. Veja [Deploys e status](/operacao/deploys-e-status/).
- **Limites do token e do time**: `GET /v1/me` e `GET /v1/limits`.