Error Codes - Runbase Docs

Known API errors return a JSON body with this structure:

{
  "error": {
    "message": "Human-readable description",
    "code": "error_code"
  }
}

Error reference

400 Bad Request

Code	Cause	Fix
`invalid_json`	Request body is not valid JSON	Check your JSON syntax
`missing_model`	`model` field missing or not a string	Include `"model": "provider/name"` in your request body
`missing_input`	`input` field missing or not an object	Include `"input": {...}` in your request body
`invalid_input`	Input doesn't match the model's schema	Check the model's API reference for required fields and valid values
`model_not_found`	The model ID doesn't match any available model	See the models page for valid model IDs

401 Unauthorized

Code	Cause	Fix
`missing_api_key`	No `Authorization` header or wrong format	Include `Authorization: Bearer sk-...` in your request
`invalid_api_key`	Key is invalid, disabled, or expired	Create a new key or re-enable the existing one in Settings → API Keys

402 Payment Required

Code	Cause	Fix
`insufficient_balance`	Your balance is too low for this run	Top up your balance in Settings → Credits

403 Forbidden

Code	Cause	Fix
`api_key_spend_limit_exceeded`	The key's lifetime spend limit has been reached	Raise the spend limit in Settings → API Keys
`ip_not_allowed`	Your IP is not in the key's whitelist	Add your IP to the key's allowed list, or remove the whitelist

429 Too Many Requests

Code	Cause	Fix
`RATE_LIMITED`	Too many requests in a short window	Wait and retry. See rate limits
`USAGE_EXCEEDED`	The key's usage quota is exhausted	Contact support or create a new key

404 Not Found

Code	Cause	Fix
`run_not_found`	No run with this ID for your account	Check the run ID is correct and was created with this API key

500 Internal Server Error

An unexpected error on our side. If this persists, contact support@runbase.net.

Handling errors in code

response=$(curl -s -w "\n%{http_code}" https://runbase.net/api/v1/runs \
  -H "Authorization: Bearer $RUNBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "google/nano-banana-2", "input": {"prompt": "test"}}')
 
http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | head -1)
 
if [ "$http_code" -ne 201 ]; then
  echo "Error $http_code: $(echo $body | jq -r '.error.message')"
fi

For 429 errors, implement exponential backoff — wait 1s, then 2s, then 4s before retrying.