Erros

Códigos de status HTTP

200 / 201 / 204Sucesso. 201 quando algo foi criado, 204 quando não há corpo.

400Bad Request: requisição malformada ou campo inválido.

401Unauthorized: credenciais ausentes ou inválidas.

404Not Found: o recurso não existe neste workspace.

429Too Many Requests: aguarde o número de segundos indicado em Retry-After.

5xxErro do servidor. É seguro repetir requisições idempotentes com backoff.

Corpo de erro (v3)

{
  "status": 400,
  "code": "INVALID_FIELD",
  "message": "Request validation failed.",
  "details": [
    { "field": "code", "message": "must be unique in the workspace" }
  ]
}

Campo	Tipo	Descrição
status	integer	Código de status HTTP
code	string	Código de erro estável e legível por máquina. Use este campo na lógica, não message.
message	string	Mensagem legível por pessoas
details	array	Problemas por campo, quando o corpo da requisição é inválido

Corpo de erro (v1)

Os endpoints legados retornam um formato menor:

{ "code": 1001, "message": "Store not found" }

Tratando erros

JavaScript

const res = await fetch(url, { headers })
if (!res.ok) {
  const error = await res.json().catch(() => ({}))
  if (res.status === 429) {
    await sleep(Number(res.headers.get('Retry-After') ?? 1) * 1000)
    // tentar novamente
  }
  throw new Error(`${res.status} ${error.code ?? ''}: ${error.message ?? res.statusText}`)
}

Python

response = session.get(url)
if response.status_code == 429:
    time.sleep(int(response.headers.get("Retry-After", "1")))
elif not response.ok:
    error = response.json()
    raise RuntimeError(f"{response.status_code} {error.get('code')}: {error.get('message')}")