Errors

Complete list of API error codes, rate limit handling, and retry strategies for the AskVerdict API.

1 min read
Share

All API errors return a consistent JSON structure with an error code and human-readable message.

Error Response Format

json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "A human-readable description of what went wrong"
  }
}

Error Codes

Authentication Errors (401)

CodeDescription
UNAUTHORIZEDMissing or invalid API key
API_KEY_REVOKEDThe API key has been revoked
API_KEY_EXPIREDThe API key has expired

Authorization Errors (403)

CodeDescription
FORBIDDENYour plan doesn't support this feature
BYOK_REQUIREDThis mode requires BYOK subscription

Validation Errors (400)

CodeDescription
VALIDATION_ERRORRequest body failed validation (details in message)
INVALID_MODEUnrecognized debate mode
QUESTION_TOO_LONGQuestion exceeds 2000 character limit

Payment Errors (402)

CodeDescription
INSUFFICIENT_CREDITSNot enough credits for the selected mode

Rate Limit Errors (429)

CodeDescription
RATE_LIMITEDToo many requests. Check X-RateLimit-Reset header.

Not Found (404)

CodeDescription
NOT_FOUNDResource doesn't exist or you don't have access

Server Errors (500)

CodeDescription
INTERNAL_ERRORSomething went wrong on our end
PROVIDER_ERRORAI provider returned an error (retry may help)
PROVIDER_TIMEOUTAI provider timed out

Rate Limit Headers

Every response includes rate limit information:

plaintext
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1708444800

Retry Strategy

For 429 and 5xx errors, implement exponential backoff: wait 1s, 2s, 4s, 8s with jitter. Max 3 retries.

typescript
async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      const isRetryable = error.status === 429 || error.status >= 500;
      if (!isRetryable) throw error;
      const delay = Math.min(1000 * 2 ** i, 8000) + Math.random() * 1000;
      await new Promise((r) => setTimeout(r, delay));
    }
  }
  throw new Error("Unreachable");
}

Was this page helpful?

PreviousDelete VerdictNextDebates API