Errors

Every non-2xx response from the REST API uses a single error envelope:

{
  "error": {
    "code": "insufficient_credits",
    "message": "You need 3 credits for this call; balance is 1.",
    "request_id": "req_01J7K9..."
  }
}

The MCP server wraps the same error in its own protocol envelope but the code, message, and request_id fields are preserved.

Status codes

Status	Code	When it happens	Retry?
`400`	`bad_request`	Malformed JSON, missing required field, invalid value.	No — fix and resend.
`401`	`unauthenticated`	Key missing, malformed, or revoked.	No.
`402`	`insufficient_credits`	Authenticated, but the call requires more credits than your balance.	No — top up.
`403`	`forbidden`	Key valid but not authorised for this endpoint or resource.	No.
`404`	`not_found`	Unknown niche slug, unknown score ID, etc.	No.
`422`	`unprocessable`	Validation passed type-check but failed business rules (e.g. unreachable thumbnail URL).	Sometimes — see message.
`429`	`rate_limited`	Plan rate limit exceeded. Response includes `Retry-After` header.	Yes, after delay.
`500`	`internal`	Unexpected server error. We’re already alerted.	Yes, with backoff.
`502 / 503 / 504`	`unavailable`	Upstream model or dependency timeout.	Yes, with backoff.

Idempotency and credits

Credits debit only on success (2xx). Any non-2xx response is free. This means safely retrying transient failures (5xx, 429) never double-charges you.

For POST endpoints (scoring, benchmarking) you can also pass an Idempotency-Key header — repeating the same key within 24 hours returns the original response without consuming credits a second time.

Retry strategy

For 429 and 5xx, retry with exponential backoff:

attempt 1 → wait 1s
attempt 2 → wait 2s
attempt 3 → wait 4s
…
cap at 60s, max 5 attempts

For 429, honour the Retry-After header if present (its value, in seconds, overrides the backoff). All three SDKs implement this by default; you can disable via retries=0.

Error classes in SDKs

Class	Maps to
`BadRequestError`	400, 422
`AuthenticationError`	401, 403
`InsufficientCreditsError`	402
`NotFoundError`	404
`RateLimitError`	429
`ServiceUnavailableError`	500, 502, 503, 504
`NetworkError`	Connection / DNS / timeout failures before a response

See SDKs for usage examples.