Errors
Handle Clawdbase failures without losing the reason or retrying unsafely.
| HTTP | Typical cause | Client action |
|---|---|---|
| 202 | An earlier request with the same idempotency key is still pending | Do not treat the body as success; retry the identical request after a short delay |
| 400 | Invalid JSON, missing operation/subject/idempotency key, unknown operation | Fix the request; do not retry unchanged |
| 401 | Missing, invalid, revoked or expired bearer credential | Rotate or reauthenticate |
| 402 | Allowance and eligible credit sources are exhausted | Upgrade, add credits or wait for renewal |
| 403 | Authenticated caller selected a key it does not own, supplied a mismatched api_key_id, or lacks scope | Use the correct owned and scoped key |
| 404 | canonical_subject_not_found: no canonical Agent or Skill matches the input | Check the Page's canonical UUID and selected operation; no credits were charged |
| 409 | canonical_subject_ambiguous: more than one Agent or Skill matches the input | Use the intended Page's canonical UUID; a shared repository does not identify one Agent. No credits were charged |
| 409 | canonical_lineage_unavailable: no confirmed Creator relationship exists for the selected artifact | Use the separate Agent/Skill operation, or retry Lineage after its Creator relationship is established. No credits were charged |
| 409 | An idempotency key was reused with a different operation, subject, channel or Access Key | Replay the original request or use a new key for the new logical operation |
| 429 | Route or account rate limit | Honor Retry-After and back off |
| 500 | Billing reserve or settlement system error | Retry with the same idempotency key |
| 502 | inVerus request failed | Retry with the same idempotency key; no credits were charged |
| 503 | inVerus, billing or provider service is temporarily unavailable | Retry with the same idempotency key; if it persists, contact Clawdbase support. No new charge is created for a pre-reservation failure |
Error shape
Errors always include a human-readable error. Some routes add code or ledger_id. The operation route never returns raw inVerus or billing-provider details to the client; a 502 carries the sanitized message The scoring service is temporarily unavailable. No credits were charged. Please try again. Treat all error fields as additive and show customers the safe message.
The Console presents concise provider and API errors while retaining safe correlation details for support.
Error handling example
type ApiError = {
error?: string
code?: string
details?: string
ledger_id?: string
}
async function parseClawdbaseResponse(response: Response) {
const body = (await response.json().catch(() => ({}))) as ApiError
if (response.ok) return body
const error = new Error(body.error ?? `Clawdbase returned ${response.status}`)
Object.assign(error, { status: response.status, code: body.code, ledgerId: body.ledger_id })
throw error
}Log status, safe code, ledger ID, operation and your own request/job ID. Do not log the Authorization header, provider token, session cookie or full upstream error payload.
Retry matrix
| Status | Automatic retry? | Requirement |
|---|---|---|
| 202 | Yes, bounded | Same body and idempotency key after a short delay |
| 400 | No | Correct the body or operation |
| 401 | No | Reauthenticate or rotate the credential |
| 402 | No | Restore eligible allowance or credits |
| 403 | No | Correct key ownership, explicit api_key_id, or scopes |
| 404 | No | Correct the canonical subject reference |
| 409 | No | Read code: resolve ambiguous identity or missing lineage; for idempotency conflicts replay the original request or use a new key for a new logical operation |
| 429 | Yes, bounded | Exponential backoff and Retry-After |
| 500 | Yes, bounded | Same body and idempotency key |
| 502 | Yes, bounded | Same idempotency key; reservation was reversed |
| 503 | Yes, bounded | Retry after a delay with the same idempotency key; contact support if it persists |
Console messaging
Provider ownership conflicts state that the account belongs to another Clawdbase user and offer account selection or intentional sign-out. Billing errors keep the current plan visible. Scoring errors preserve the last confirmed score and timestamp instead of replacing them with zero.
Escalation data
Provide timestamp, route, operation, safe subject reference, status, code and ledger ID. For OAuth, include the provider and the page you returned to, never the authorization query. For billing, share a Checkout Session ID only through the secure support channel and never share an Access Key or payment credential.