Start building
SandBase

Appearance

API Errors ​

SandBase uses standard HTTP status codes, but it does not expose one universal error body. Branch on the HTTP status first, then parse the response schema documented for the endpoint you called. Do not require every error to contain code, param, message, or request_id.

Response shapes ​

Core middleware and several /v1/* endpoints return a flat error:

json
{"error":"API key rate limit exceeded"}

Agent resource APIs can return a typed error object:

json
{"error":{"type":"invalid_request","message":"invalid request body"}}

OpenAI-compatible endpoints retain an OpenAI-compatible envelope. POST /v1/messages retains an Anthropic-compatible envelope:

json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required"
  }
}

Use the OpenAPI specification for the exact status codes and schemas of a public operation.

HTTP status handling ​

StatusTypical meaningClient action
400Invalid input or unsupported parameterFix the request using the endpoint and selected model schema.
401Missing, invalid, revoked, or expired credentialReplace or rotate the credential; do not retry unchanged.
402The request cannot be funded or a spending limit was reachedResolve the balance or key limit before retrying.
403The credential lacks permission, or a compatibility endpoint maps a spending failure to 403Inspect the endpoint-specific envelope and use an authorized key.
404Model or resource is unavailable to the callerVerify the current model ID or resource ID.
409Resource state conflictRead the latest state before deciding whether a retry is safe.
422Semantically invalid resource inputCorrect the documented field values.
429Per-key or platform-wide request protectionRetry with bounded backoff and jitter when the operation is safe to repeat.
500, 502, 503, 504SandBase or upstream failureRetry only when the operation is safe to repeat.

Not every endpoint documents every status in this table. The operation's OpenAPI response map is authoritative.

Authentication errors ​

Documented authentication messages include:

  • missing API key in Authorization header
  • invalid API key
  • API key has been revoked
  • API key has expired
  • insufficient_scope

Use Authorization: Bearer $SANDBASE_API_KEY for standard endpoints. POST /v1/messages also accepts x-api-key; protocol-compatible Google endpoints document their own supported key headers.

A revoked key cannot be re-enabled. Create a replacement, update the consuming application, verify it, and then remove any remaining references to the old key.

Rate limits ​

Documented flat messages include API key rate limit exceeded and global rate limit exceeded. SandBase does not publish one universal numeric limit because the effective limit can vary by key and platform capacity.

If a response includes Retry-After, respect it. Otherwise use bounded exponential backoff with jitter. See Rate limits for request-smoothing patterns.

Video submissions have two additional checks. organization concurrency limit exceeded (429) means your organization already has as many tasks in progress as its account level allows; it clears when a running task finishes. insufficient credit for estimated video cost (402) means the estimated cost is more than your balance plus credit line; top up before retrying. See Concurrency limits.

Retry safety ​

Use this decision order:

  1. Determine whether the operation has already produced an externally visible effect.
  2. Do not retry an unchanged 400, 401, 402, 403, 404, or 422 request.
  3. For 409, read the current resource state before retrying.
  4. Retry 429 and transient 5xx responses only a small, bounded number of times.
  5. Before repeating a create, trigger, upload, or external-action request, confirm that the operation is idempotent or that your application can reconcile duplicates.

A suitable delay is:

text
delay = min(base_delay * 2^attempt, max_delay) + random_jitter

Streaming failures ​

After a stream starts, an error may arrive in that protocol's stream format instead of as a new HTTP response. Treat the stream as incomplete, retain any partial output your application needs, and retry only when regenerating the request is safe. Do not assume every provider emits the same terminal event or finish reason.

Operational debugging ​

Record the endpoint, HTTP status, selected model or resource ID, timestamp, and any safe request identifier returned by the server. Never log authorization headers, API keys, credential values, or sensitive prompt content.

Use Console → Activities to inspect organization request history. When reporting a persistent failure, include sanitized request metadata and the smallest reproducible request.

See also ​