Errors & rate limits

Error envelope

Most errors return the standard envelope:

{
	"statusCode": 401,
	"message": "invalid api key",
	"error": "Unauthorized",
	"requestId": "9f2c1e0a-…"
}

Two variations to handle:

• Validation failures put an array of messages in message:

  {
  	"statusCode": 400,
  	"message": ["provider must be a string", "messages must contain at least 1 elements"],
  	"error": "Bad Request",
  	"requestId": "…"
  }

• Domain errors from some endpoints use a compact shape with a machine-readable code and no statusCode field in the body (the HTTP status still applies):

  { "error": "miner_not_registered_to_org", "requestId": "…" }

Robust clients should key off the HTTP status first, then inspect message/error.

requestId is always present and matches the X-Request-Id response header — include it in support requests.

Strict validation

Request bodies are validated strictly:

• Unknown properties are rejected with 400 (not silently dropped). If you send max_tokens instead of maxTokens, you get a validation error rather than an ignored parameter — a deliberate guard against silent misconfiguration.
• Values are coerced where unambiguous (e.g. numeric strings in query params).

Rate limits

Two independent layers apply:

On authenticated requests, X-RateLimit-Limit and X-RateLimit-Remaining report the per-key window. A 429 includes Retry-After (seconds until the window resets).

For validators: a 429 on a signed request refunds the nonce, so the identical signed request can be safely retried after Retry-After — see validator auth.

Common statuses

Size limits

• JSON bodies: 1 MB
• Agent uploads (application/octet-stream): 2 MB