Errors
The envelope
Section titled “The envelope”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.
Status codes
Section titled “Status codes”| Status | type | Meaning | Retry? |
|---|---|---|---|
400 | ValidationError | The request itself was malformed — a bad field, a missing required value. | No. Fix the request. |
401 | UnauthorizedError | Missing, malformed, revoked, or expired credentials. | No. Check the key. |
402 | PaymentRequiredError | This key’s organization is on a free plan, which reaches only the Zapier endpoints and POST /audits/{auditId}/prompts/bulk. | No. Upgrade the plan. |
403 | ForbiddenError | The 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. |
404 | NotFoundError | No such resource — or it belongs to another organization. | No. |
409 | ConflictError | The resource is in a state that does not permit this change — editing configuration mid-run, for instance. | Yes, once the state changes. |
422 | UnprocessableEntityError | The request was well-formed but its contents cannot be processed. | No. Fix the contents. |
429 | RateLimitError | Too many requests, or a plan allowance used up — the content allowance answers 429 with error.details.nextResetAt. | Yes, with backoff — or after nextResetAt. |
500 | InternalError | Something failed on our side. | Yes, with backoff. |
What to retry
Section titled “What to retry”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 404 that should be a 403
Section titled “A 404 that should be a 403”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.
Failures that are not errors
Section titled “Failures that are not errors”Two responses look like problems and are not:
202 AcceptedfromPOST /audits/{auditId}/startandPOST /audits/{auditId}/run. The work is enqueued, not finished. PollGET /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
effectiveConnectorsanddroppedConnectors. 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.