Skip to main content
All Tuteliq API errors return a consistent JSON structure with a machine-readable code and a human-readable message: 
{
  "error": {
    "code": "AUTH_1002",
    "message": "Invalid API key"
  }
}

​
Error Codes

​
Authentication (AUTH_1xxx)

CodeHTTPDescription
AUTH_1001401API key is required
AUTH_1002401Invalid API key
AUTH_1003401API key has been revoked
AUTH_1004401API key is inactive
AUTH_1005401API key has expired
AUTH_1006401Unauthorized access
AUTH_1007403Access forbidden
AUTH_1008503Authentication service unavailable

​
Rate Limiting (RATE_2xxx)

CodeHTTPDescription
RATE_2001429Rate limit exceeded
RATE_2002429Daily request limit exceeded
RATE_2003429Request quota exceeded

​
Validation (VAL_3xxx)

CodeHTTPDescription
VAL_3001400Validation failed
VAL_3002400Invalid input provided
VAL_3003400Missing required field
VAL_3004400Invalid format
VAL_3005400Batch size exceeds maximum allowed

​
Service (SVC_4xxx)

CodeHTTPDescription
SVC_4001500An unexpected error occurred
SVC_4005500AI analysis service error
SVC_4007503LLM service is temporarily unavailable

​
Not Found (NF_5xxx)

CodeHTTPDescription
NF_5001404Resource not found
NF_5002404Endpoint not found
NF_5003404User not found

​
Analysis (ANALYSIS_6xxx)

CodeHTTPDescription
ANALYSIS_6001500Analysis failed
ANALYSIS_6002400Unsupported analysis type
ANALYSIS_6003400File exceeds maximum allowed size
ANALYSIS_6004400File type is not supported
ANALYSIS_6005400File is required but was not provided
ANALYSIS_6006500Audio transcription failed
ANALYSIS_6007500Image analysis failed

​
Subscription (SUB_7xxx)

CodeHTTPDescription
SUB_7001403No active subscription found
SUB_7002403Subscription is inactive
SUB_7003403Subscription has expired
SUB_7004429Message limit reached
SUB_7005429Credits depleted
SUB_7006403Endpoint not available on your current plan

​
GDPR (GDPR_8xxx)

CodeHTTPDescription
GDPR_8001500Failed to delete user data
GDPR_8002500Failed to export user data
GDPR_8004404Consent record not found
GDPR_8005400Consent has already been withdrawn
GDPR_8009400Invalid consent type
GDPR_8010403Required consent not granted

​
WebSocket (WS_10xxx)

CodeHTTPDescription
WS_10001401WebSocket authentication failed
WS_10002429WebSocket connection limit reached
WS_10003400Audio buffer exceeded maximum size
WS_10004400Session exceeded maximum duration
WS_10005400Invalid WebSocket message format
WS_10006500Real-time transcription failed

​
Retry Strategy

Not all errors should be retried. Here’s a guide:
Error TypeRetry?Strategy
AUTH_*NoFix your API key or permissions
RATE_2001YesWait for the Retry-After header value, then retry
VAL_*NoFix the request payload
SVC_4001, SVC_4005YesExponential backoff, max 3 retries
SVC_4007YesWait 5-10 seconds, then retry
NF_*NoCheck the endpoint URL or resource ID
ANALYSIS_6001, 6006, 6007YesRetry once after a short delay
SUB_7005NoPurchase more credits

​
Exponential backoff example

async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error instanceof TuteliqError) {
        // Don't retry client errors
        if (error.status < 500 && error.code !== "RATE_2001") throw error;
      }
      if (attempt === maxRetries) throw error;
      const delay = Math.min(1000 * 2 ** attempt, 10000);
      await new Promise((r) => setTimeout(r, delay));
    }
  }
  throw new Error("Unreachable");
}

const result = await withRetry(() =>
  tuteliq.detectUnsafe({ text: "message", ageGroup: "10-12" })
);
The Node.js and Python SDKs have built-in retry logic. Set retries: 2 (Node.js) or retries=2 (Python) in the client constructor to enable automatic retries with exponential backoff.

​
SDK Error Handling

All Tuteliq SDKs throw typed error objects that you can catch and inspect: 
import Tuteliq, { TuteliqError } from "@tuteliq/sdk";

try {
  const result = await tuteliq.detectUnsafe({
    text: "some content",
    ageGroup: "10-12",
  });
} catch (error) {
  if (error instanceof TuteliqError) {
    console.error(error.code);    // "AUTH_1002"
    console.error(error.message); // "Invalid API key"
    console.error(error.status);  // 401
  }
}