Skip to main content

​
API error codes and HTTP status mapping

Every EvalGate error code, its HTTP status, what it means, and how to handle errors in TypeScript and Python with try/catch examples.
When a request fails, EvalGate always returns a JSON object in the same envelope shape — regardless of the HTTP status code. Parsing this envelope lets you handle every error class in a single place.

​
Error envelope

Every error response has this structure: 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "name is required",
    "details": null,
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
​
error.code
string
A machine-readable constant identifying the error class. Use this field for programmatic error handling — never parse message.
​
error.message
string
A human-readable description of what went wrong. Suitable for logs and development debugging; do not display this to end users without filtering.
​
error.details
unknown | null
Optional additional context. For VALIDATION_ERROR, this contains a Zod issues array describing which fields failed and why. null for all other codes.
​
error.requestId
string
A UUID that uniquely identifies the request on EvalGate’s servers. Include this value in any support ticket — the team can use it to locate the exact request in logs. The same UUID appears in the x-request-id response header.

​
Error codes and HTTP status mapping

CodeHTTP statusWhen it occurs
UNAUTHORIZED401Missing or invalid API key
FORBIDDEN403Key lacks required scope for this resource
NO_ORG_MEMBERSHIP403Authenticated user is not a member of the target organization
QUOTA_EXCEEDED403Organization has reached a usage limit (upgrade required)
NOT_FOUND404Resource does not exist, or the ID belongs to a different organization
VALIDATION_ERROR400Request body or query parameters failed schema validation
CONFLICT409A resource with the same identifier already exists
RATE_LIMITED429Too many requests — back off and retry after the X-RateLimit-Reset time
INTERNAL_ERROR500Unexpected server error — include the requestId when contacting support
SERVICE_UNAVAILABLE503EvalGate is temporarily unavailable — retry with exponential backoff
QUOTA_EXCEEDED and NO_ORG_MEMBERSHIP both map to HTTP 403. Distinguish them by the code field, not the status code.

​
Handling errors in code

import { AIEvalClient } from '@evalgate/sdk';

const client = AIEvalClient.init();

try {
  const evaluation = await client.evaluations.create({
    name: 'My eval',
    type: 'unit_test',
  });
  console.log('Created:', evaluation.id);
} catch (err: unknown) {
  if (err instanceof Error && 'code' in err) {
    const apiErr = err as { code: string; message: string; requestId?: string };
    switch (apiErr.code) {
      case 'UNAUTHORIZED':
        console.error('Check your EVALGATE_API_KEY environment variable.');
        break;
      case 'RATE_LIMITED':
        console.error('Rate limit hit — retrying after backoff.');
        break;
      case 'VALIDATION_ERROR':
        console.error('Invalid request:', apiErr.message);
        break;
      default:
        console.error(`API error ${apiErr.code}: ${apiErr.message}`);
        console.error('Request ID for support:', apiErr.requestId);
    }
  } else {
    throw err;
  }
}
When retrying after a 429 RATE_LIMITED response, read the X-RateLimit-Reset header to determine the exact time the window resets, rather than using a fixed sleep duration. The TypeScript SDK handles this automatically with exponential backoff.