Core concepts

Errors

One envelope, one set of codes, and a field-level breakdown on validation failures.

Every failure comes back in the same shape, whatever went wrong. Branch on error.code, not on the message — messages are written for people and will change.

JSON

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body failed validation",
    "details": [
      { "path": "title", "message": "String must contain at least 1 character" }
    ]
  }
}

Status codes

Status	Code	Means
`400`	`BAD_REQUEST`	Malformed JSON, or a query parameter the endpoint cannot read
`401`	`UNAUTHORIZED`	No key, or one that is unknown, revoked or expired — deliberately indistinguishable
`403`	`FORBIDDEN`	The key is read only and this is a write
`404`	`NOT_FOUND`	No such record, or the key cannot see it
`409`	`CONFLICT`	The change collides with the current state
`422`	`VALIDATION_ERROR`	The body parsed but failed the schema; see `details`
`429`	`RATE_LIMITED`	Too many requests; see Rate limits
`5xx`	`INTERNAL_ERROR`	Ours. Safe to retry with backoff

Anything belonging to another account returns 404, never 403. An id can never be used to learn that a record exists — including a member id in an organization you are not in.

Handling them

const response = await fetch(url, { headers });

if (!response.ok) {
  const { error } = await response.json();

  if (error.code === "RATE_LIMITED") return retryAfter(response);
  if (error.code === "VALIDATION_ERROR") throw new BadInput(error.details);

  throw new Error(`${error.code}: ${error.message}`);
}

const { data } = await response.json();

Retrying

Retry 429 and 5xx. Never retry 4xx — the request will fail the same way, and a retry loop on 401 will get the key rate limited on top.

Use exponential backoff with jitter, capped at a minute. Write operations accept an Idempotency-Key header so a retry after a timeout cannot create the same record twice.

Shell

curl -X POST https://api-notetaker.nabrah.ai/ext/v1/bots \
  -H "Authorization: Bearer $NABRAH_API_KEY" \
  -H "Idempotency-Key: 7f3c1e90-2f1a-4c0e-9a3b-9d2e5f6a7b8c" \
  -H "Content-Type: application/json" \
  -d '{"joinUrl":"https://meet.google.com/abc-defg-hij"}'

PreviousAuthentication NextPagination

For agents:this page as Markdownllms.txtfull text