Skip to main content
When an API request fails, Velobase returns a standard JSON error response alongside an appropriate HTTP status code.

​
Error Format

All errors return a structured error object containing three fields: 
{
  "error": {
    "message": "insufficient balance in selected credit_types",
    "type": "bad_request",
    "code": "insufficient_balance_in_selected_credit_types"
  }
}
FieldTypeDescription
error.messagestringA human-readable description of what went wrong. Use this for logs and user-facing messages.
error.typestringA high-level category: bad_request, auth_error, not_found, conflict, too_many_requests, server_error.
error.codestringA 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.
These errors occur when the Authorization header is missing, malformed, or the key has been deactivated.
CodeDescription
missing_api_keyNo API key was provided in the Authorization header.
invalid_api_keyThe provided API key is malformed or does not exist.
api_key_revokedThe API key has been revoked in the dashboard.
These errors occur when request parameters are invalid or a referenced resource does not exist.
CodeHTTPDescription
invalid_starts_at400The starts_at parameter is not a valid ISO 8601 datetime.
invalid_expires_at400The expires_at parameter is not a valid ISO 8601 datetime.
invalid_credit_types400The credit_types array is empty or contains invalid strings.
customer_not_found404The requested customer_id does not exist.
These errors occur when a billing operation cannot be completed due to insufficient funds or an invalid operation sequence.
CodeDescription
insufficient_balanceThe customer does not have enough total available credits.
insufficient_balance_in_selected_credit_typesThe customer has enough credits overall, but not within the specific credit_types requested.
no_consumable_freeze_recordsYou attempted to consume a transaction that was never frozen or cannot be found.
freeze_records_already_consumedThe frozen credits for this transaction_id have already been consumed.
no_unfreezable_recordsYou attempted to unfreeze a transaction that was never frozen, or has already been consumed or unfrozen.
actual_amount_exceeds_frozen_amountThe amount passed to consume is greater than the amount originally frozen for this transaction.
These errors indicate a conflict between two requests or an unexpected internal failure.
CodeHTTPDescription
transaction_conflict409The transaction_id was already used for a different customer.
customer_scope_mismatch409An operation referenced a record belonging to a different customer.
billing_account_not_found500An internal inconsistency where an expected billing account is missing.
server_error500An unexpected internal error occurred on the Velobase servers.