Skip to content

Errors

Every endpoint answers with the same envelope. On success:

{ "success": true, "data": { } }

On failure, the same envelope with success: false and an error object:

{
"success": false,
"error": {
"message": "Audit not found",
"type": "NotFoundError"
}
}

message is human-readable and may change. type is the machine-readable class of failure and is the field to branch on. Some errors carry more in error.details — a refused edit names its details.code, an all-or-none import lists its refused details.rows — so read the object permissively rather than assuming exactly two fields.

StatustypeMeaningRetry?
400ValidationErrorThe request itself was malformed — a bad field, a missing required value.No. Fix the request.
401UnauthorizedErrorMissing, malformed, revoked, or expired credentials.No. Check the key.
402PaymentRequiredErrorThis key’s organization is on a free plan, which reaches only the Zapier endpoints and POST /audits/{auditId}/prompts/bulk.No. Upgrade the plan.
403ForbiddenErrorThe key’s scope or role does not permit this — a read-only key attempting a write, or a key whose creator is now a viewer.No. Use a read-write key held by an editor.
404NotFoundErrorNo such resource — or it belongs to another organization.No.
409ConflictErrorThe resource is in a state that does not permit this change — editing configuration mid-run, for instance.Yes, once the state changes.
422UnprocessableEntityErrorThe request was well-formed but its contents cannot be processed.No. Fix the contents.
429RateLimitErrorToo many requests, or a plan allowance used up — the content allowance answers 429 with error.details.nextResetAt.Yes, with backoff — or after nextResetAt.
500InternalErrorSomething failed on our side.Yes, with backoff.

Only two classes of failure are worth retrying: 429 and 5xx. Everything else is a statement about your request that will be equally true the second time.

async function call(path: string, init?: RequestInit) {
for (let attempt = 0; attempt < 5; attempt++) {
const response = await fetch(`https://api.beket.ai/api/v1${path}`, init);
if (response.ok) return response.json();
// 4xx other than 429 will not become true on a retry.
if (response.status !== 429 && response.status < 500) {
const { error } = await response.json();
throw new Error(`${error.type}: ${error.message}`);
}
await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
}
throw new Error('Giving up after 5 attempts');
}

Rate limits may change while the API is in beta, so treat 429 as an expected response and back off, rather than tuning a client to a specific rate.

A request for a resource belonging to another organization returns 404, not 403 — the API does not confirm that a resource it will not show you exists. When a 404 arrives for an id you believe is real, check which organization the key belongs to before concluding the resource was deleted. See Authentication.

Two responses look like problems and are not:

  • 202 Accepted from POST /audits/{auditId}/start and POST /audits/{auditId}/run. The work is enqueued, not finished. Poll GET /audits/{auditId}/run.
  • A clamped selection. Selecting more connectors than the plan allows does not fail — the selection is clamped, and the response tells you what was kept in effectiveConnectors and droppedConnectors. Read them back rather than assuming.

A run that fails is also not an HTTP error: GET /audits/{auditId}/run answers 200 with runStatus: "failed". Check the field, not just the status code.