Errors

HTTP status codes

200 / 201 / 204Success. 201 when something was created, 204 when there is no body.

400Bad Request: malformed request or invalid field.

401Unauthorized: missing or invalid credentials.

404Not Found: the resource does not exist in this workspace.

429Too Many Requests: wait for Retry-After seconds.

5xxServer error. Safe to retry idempotent requests with backoff.

Error body (v3)

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

Field	Type	Description
status	integer	HTTP status code
code	string	Stable, machine-readable error code. Branch on this, not on message.
message	string	Human-readable message
details	array	Field-level problems, when the request body is invalid

Error body (v1)

Legacy endpoints return a smaller shape:

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

Handling errors

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