Open Kweko
DocsAPI referenceWebhooksErrorsApps Open Kweko kweko.uz

Get started

Errors

Errors use HTTP status codes and a JSON body with a stable, machine-readable code. Every error links to its own page here.

The error format

json
{
  "error": {
    "code": "validation_failed",
    "message": "Some fields need attention.",
    "request_id": "req_4f2a9c1e0b7d3a55",
    "docs_url": "https://developers.kweko.uz/errors/validation_failed",
    "fields": {
      "stage_id": "This stage belongs to another pipeline."
    }
  }
}
FieldMeaning
codeWhat went wrong, in snake_case. Stable: branch on it.
messageA sentence for people, in the language of Accept-Language (English, Russian or Uzbek). It can change: do not parse it.
request_idThe id of this request, also in the X-Request-Id header. Quote it to support.
docs_urlThis site's page for the code.
fieldsOnly for field problems: request field name to a message about it.

Some codes add more keys next to these, for example permission on forbidden, reason and limit on rate_limited, or key, limit, used, plan and upgrade_to on limit_reached. Each code's page lists them.

OAuth's token endpoint (POST /oauth/token) is the one exception: it answers in the OAuth format, {"error": "invalid_grant", "error_description": "…"}, see OAuth for apps.

Status codes

StatusMeaningRetry?
400The request is malformed: bad JSON, an unknown field, a bad cursorNo, fix the request
401No valid credentialsNo, fix the key or refresh the token
402The workspace is read-only until its subscription is paid, or out of AI creditsLater
403Authenticated, but not allowed: a missing scope, a plan limit, a restrictionNo
404Not found, or not visible to this keyNo
409Conflicts with the current state, for example an already finished importAfter changing the state
410The record was deletedNo
413The body is too largeNo, send less
422Valid JSON that cannot be accepted: validation_failed and friendsNo, fix the values
429Rate limitedYes, after Retry-After
500Kweko failedYes, with backoff
502, 503, 504A service Kweko depends on failed or is slowYes, with backoff

Handle codes you do not know by their status: new codes can appear in v1.

Handling errors

Node.js
const res = await fetch("https://api.kweko.uz/v1/leads", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.KWEKO_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Website order #1042" }),
})
if (!res.ok) {
  const { error } = await res.json()
  if (error.code === "validation_failed") showFieldErrors(error.fields)
  else if (res.status === 429 || res.status >= 500) retryLater(Number(res.headers.get("Retry-After") || 1))
  else throw new Error(`${error.code}: ${error.message} (${error.request_id})`)
}

All error codes

Generated from the API's source code on every build, so it lists every code the API can return. Codes marked as Kweko Admin come from the staff back office and never reach API clients.

The API has 218 error codes today. Each has its own page.