Errors

CleverThis uses standard HTTP status codes and returns structured JSON error bodies. The error body is always in the following shape for both the inference API and the A2A control plane.

Error response shape

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your workspace has insufficient credits. Top up at https://app.cleverthis.com/billing.",
    "type": "billing_error",
    "param": null,
    "request_id": "req_abc123xyz"
  }
}

HTTP status codes

Status	Meaning
400	Bad Request — malformed JSON, missing required fields, or invalid parameter values
401	Unauthorized — missing or invalid API key
402	Payment Required — wallet balance is zero or below zero
403	Forbidden — valid key used against the wrong API surface (e.g. inference key on A2A)
404	Not Found — model not deployed in this namespace, or resource not found
422	Unprocessable Entity — request is well-formed but semantically invalid (e.g. Actor YAML validation failure)
429	Too Many Requests — rate limit exceeded
500	Internal Server Error — unexpected error in CleverThis
502	Bad Gateway — error from upstream provider
503	Service Unavailable — deployment is stopping or temporarily unavailable

Common error codes

error.code	Status	Description
invalid_api_key	401	Key is malformed or does not exist
revoked_api_key	401	Key has been revoked
insufficient_credits	402	Wallet balance too low
model_not_found	404	Requested model is not deployed in this namespace
namespace_not_found	404	Namespace does not exist
actor_validation_error	422	Actor YAML failed schema validation
rate_limit_exceeded	429	Per-minute request or token rate limit hit
upstream_error	502	Provider returned an error
context_length_exceeded	400	Messages exceed the model's context window

Retries

For 429 and 503 responses, the response includes a Retry-After header indicating the number of seconds to wait before retrying. For 502 errors, implement exponential backoff with jitter.

Coming soon

A complete error code registry with resolution guidance is being added to this page.