Handling Errors

When an API request fails, Velobase returns a standard JSON error response alongside an appropriate HTTP status code. The same error shape applies to every surface: model gateway calls (POST /v1/chat/completions, POST /v1/messages), customer and deposit endpoints, and the billing primitives you use for work you price yourself (POST /v1/billing/freeze, /v1/billing/consume, /v1/billing/deduct, /v1/billing/unfreeze).

Most failures on the model gateway come down to one of two things: the request did not resolve an end-customer to bill (no X-Velobase-Customer header and a project key, or an expired customer-scoped key), or the customer’s wallet has no available funds. See the gateway section below.

Error Format

All errors return a structured error object containing three fields:

{
  "error": {
    "message": "insufficient available funds in customer wallet",
    "type": "bad_request",
    "code": "insufficient_balance"
  }
}

Field	Type	Description
`error.message`	string	A human-readable description of what went wrong. Use this for logs and user-facing messages.
`error.type`	string	A high-level category: `bad_request`, `auth_error`, `not_found`, `conflict`, `too_many_requests`, `server_error`.
`error.code`	string	A stable, machine-readable identifier. Use this field for all programmatic error handling.

Error Codes Reference

Below is a list of common error.code values you may encounter, organized by category.

Authentication: 401 Unauthorized

These errors occur when the Authorization header is missing, malformed, or the key has been deactivated. Both project keys (vb_live_) and customer-scoped keys (vb_customer_) authenticate here.

Code	Description
`missing_api_key`	No API key was provided in the `Authorization` header.
`invalid_api_key`	The provided API key is malformed or does not exist.
`api_key_revoked`	The API key has been revoked in the dashboard (Keys section).

Model gateway: customer resolution and routing

These errors occur on billable model calls (POST /v1/chat/completions, POST /v1/messages) when Velobase cannot decide which customer to bill, or the request targets a model that is not available. Non-billable endpoints such as GET /v1/models do not require a resolvable customer.

Code	HTTP	Description
`customer_not_found`	404	The `X-Velobase-Customer` value, or the customer bound to a `vb_customer_` key, does not match any customer.
`customer_required`	400	A project key (`vb_live_`) was used on a billable endpoint without an `X-Velobase-Customer: <user-id>` header, so there is no customer to bill.
`api_key_expired`	401	A customer-scoped key (`vb_customer_`) is past its `expiresAt`.
`model_not_found`	404	The requested model id does not exist in your project. Models are defined per project; call `GET /v1/models` for your project’s list.
`model_inactive`	404	The model exists in your project but is currently deactivated.
`model_not_allowed`	403	The model is not in the `allowedModels` whitelist for this customer-scoped key.
`prompt_cache_pricing_required`	400	The request used prompt caching, but the model has no cache prices configured. Set cache read/write prices on the model in the dashboard.

Payment required: 402

Two distinct 402 cases on billable gateway calls:

Code	Description
`insufficient_balance`	The customer’s wallet cannot cover the hold for this call. The error body includes the required and available credit amounts, so you can drive a paywall or top-up prompt from it. Fix by depositing with `POST /v1/customers/deposit`. If the request did not set `max_tokens`, the message also says so: the hold then assumes a large 8,000-token output, and setting `max_tokens` lowers `required_credits` substantially.
`byok_key_required`	The model exists, but your project has not attached an upstream provider key to it. This is an operator configuration issue, not a customer balance issue. Fix it in the dashboard’s Models section.

Validation and routing: 400 Bad Request / 404 Not Found

These errors occur when request parameters are invalid or a referenced resource does not exist.

Code	HTTP	Description
`invalid_starts_at`	400	The `starts_at` parameter is not a valid ISO 8601 datetime.
`invalid_expires_at`	400	The `expires_at` parameter is not a valid ISO 8601 datetime.
`customer_not_found`	404	The requested `customer_id` does not exist.

Wallet and deduction

These errors occur when a billing operation cannot be completed because the customer’s wallet has no available funds, or the freeze/consume/deduct sequence is invalid. They apply both to per-call model billing and to the billing primitives you use for work you price yourself.All amounts are positive integer credits (1 USD = 1,000,000 credits). Unit-suffixed fields such as amount_usd, amount_cents, or amount_credits are rejected.

Code	Description
`insufficient_balance`	The customer’s wallet does not have enough available funds. Top it up with `POST /v1/customers/deposit`.
`no_consumable_freeze_records`	You attempted to `consume` a transaction that was never frozen or cannot be found.
`freeze_records_already_consumed`	The frozen funds for this `transaction_id` have already been consumed.
`no_unfreezable_records`	You attempted to `unfreeze` a transaction that was never frozen, or has already been consumed or unfrozen.
`actual_amount_exceeds_frozen_amount`	The amount passed to `consume` is greater than the amount originally frozen for this transaction.

Concurrency and rate limiting: 409 Conflict / 429 Too Many Requests

Code	HTTP	Description
`transaction_conflict`	409	The `transaction_id` was already used for a different customer.
`customer_scope_mismatch`	409	An operation referenced a record belonging to a different customer.
Idempotency replay	409	A gateway request replayed a previously used `Idempotency-Key` header. The response says so clearly instead of double-charging; use a fresh key per new request.
Rate limited	429	Too many requests. The response includes a `Retry-After` header; back off and retry after that interval.

Server errors: 500 Internal Server Error

Code	Description
`billing_account_not_found`	An internal inconsistency where an expected wallet account is missing.
`server_error`	An unexpected internal error occurred on the Velobase servers.

Getting Started

Integration Guides

Dashboard & Management

Advanced Topics

Pricing

Error Format

Error Codes Reference

​Error Format

​Error Codes Reference

Error Format

Error Codes Reference