Errores

Códigos de estado HTTP

200 / 201 / 204Éxito. 201 cuando se creó algo, 204 cuando no hay cuerpo.

400Bad Request: solicitud mal formada o campo no válido.

401Unauthorized: credenciales ausentes o no válidas.

404Not Found: el recurso no existe en este workspace.

429Too Many Requests: espera los segundos indicados en Retry-After.

5xxError del servidor. Es seguro reintentar las solicitudes idempotentes con retroceso exponencial.

Cuerpo del error (v3)

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

Campo	Tipo	Descripción
status	integer	Código de estado HTTP
code	string	Código de error estable y legible por máquina. Basa tu lógica en este campo, no en message.
message	string	Mensaje legible para personas
details	array	Problemas a nivel de campo, cuando el cuerpo de la solicitud no es válido

Cuerpo del error (v1)

Los endpoints heredados devuelven una estructura más pequeña:

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

Manejo de errores

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)
    // reintentar
  }
  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')}")