Do not treat every failure as a bad API key.
401 missing_api_key
No bearer token was sent.
Next: Send Authorization: Bearer <key>, or run bilinc login.
401 invalid_api_key
The key is unknown, revoked, expired, or from another workspace.
Next: Create a new key and run bilinc login again.
402 payment_required
Included credits are exhausted and no Cloud credits remain.
Next: Open Account Billing or contact support.
403 capability_not_entitled
The plan does not include this operation or this recall profile.
Next: Call GET /api/cloud/status to see what this key may do, then upgrade if needed.
400 invalid_request
The payload failed validation. details.field names the offending input.
Next: Fix the input. Nothing was charged: validation runs before any credit is reserved.
404 memory_not_found
No memory with that key exists in this project. revise and forget never create.
Next: Use commit to create it, or check the key.
404 snapshot_not_found
No snapshot with that id exists in this project, or it is unreadable.
Next: List snapshots and use a current id.
409 version_conflict
expectedVersion is stale: the memory changed since you read it.
Next: Re-read the memory, re-apply your change, and retry.
409 idempotency_conflict
This idempotency key was already used with a different payload.
Next: Use a fresh key for a genuinely different request.
409 state_changed_since_preview
The project changed after the rollback preview was taken.
Next: Take a new preview, review it, then execute.
410 rollback_confirmation_expired
The rollback confirmation token aged out before it was used.
Next: Take a new preview and execute promptly.
429 rate_limited
The workspace is exceeding current throughput limits.
Next: Back off, batch work, or request Scale review.
503 cloud_runtime_unavailable
The hosted runtime is temporarily unavailable.
Next: Retryable. Check /status and retry with backoff.
503 mutation_outcome_unknown
The runtime may have applied the write, but the control plane could not persist a replayable finalization receipt.
Next: Do not retry with a new key. Send the request ID to support for reconciliation.
Errors carry a stable code, a request id, and a retry hint.
{
"error": "version_conflict",
"message": "The memory changed since the expected version was read.",
"requestId": "req_5f0c...",
"retryable": false,
"details": { "field": "expectedVersion" }
}The Python SDK raises a typed exception per code — BilincAuthError, BilincPaymentRequiredError, BilincConflictError, and so on. All of them still subclass BilincCloudError, so existing handlers keep working.
workspace: <workspace-id> api_key_prefix: bil_live_**** request_id: req_5f0c... status: 401 | 402 | 403 | 404 | 409 | 410 | 429 | 503 endpoint: /api/cloud/memory/commit timestamp: 2026-07-05T00:00:00Z reproduction: bilinc quicktest failed after login
Send the request id, never the key. Support can join it against server logs.