Error Code Reference

Complete reference of error codes, response formats, and troubleshooting guidance.

Error Response Format

All API errors follow a consistent JSON structure:

{
  "success": false,
  "data": null,
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "API key is required. Provide it via X-API-Key header.",
    "status_code": 401,
    "details": null
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

code — Machine-readable error code
message — Human-readable description
details — Additional context (field errors, limits, etc.)
request_id — Unique ID for support reference

Authentication Errors

Status	Code	Meaning
401	`AUTH_REQUIRED`	No API key provided in the request
401	`AUTH_EXPIRED`	API key has expired or been revoked
401	`AUTH_INVALID`	API key format is invalid or unrecognized
403	`FORBIDDEN`	API key lacks the required permission for this endpoint
403	`IP_BLOCKED`	Request origin IP is not in the key's allowlist
403	`CONSENT_REQUIRED`	Candidate has not consented to data sharing
403	`PRIVACY_RESTRICTED`	Requested data is restricted by privacy settings

Validation Errors (422)

Returned when request parameters fail validation. The details field contains specific field errors:

{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed",
    "status_code": 422,
    "details": {
      "fields": {
        "page_size": "Must be between 1 and 100",
        "skills": "At least one skill is required for search"
      }
    }
  },
  "meta": { "request_id": "req_xyz789" }
}

Common Field Errors

Field	Error
`gpin`	Must be a valid GPIN format (e.g., GPIN12345)
`category`	Must be one of: education, employment, skill, certification
`gpins\|emails`	Maximum 100 items per bulk request
`page_size`	Must be between 1 and 100

Resource Errors (404)

Returned when a requested resource does not exist or is not accessible:

Code	Context
`NOT_FOUND`	Profile not found for the given GPIN
`NOT_FOUND`	Pool entry does not exist
`NOT_FOUND`	Export job ID not found or belongs to another key

Rate Limiting (429)

{
  "success": false,
  "data": null,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Retry after 45 seconds.",
    "status_code": 429,
    "details": {
      "limit": 60,
      "remaining": 0,
      "reset_at": 1691452845
    }
  },
  "meta": { "request_id": "req_rate123" }
}

Response includes Retry-After header with seconds until the window resets.

Payment Required (402)

Code	Meaning
`CREDITS_EXHAUSTED`	API credits depleted for the current billing period
`SUBSCRIPTION_REQUIRED`	Endpoint requires a higher subscription tier

Conflict (409)

Code	Meaning
`CONFLICT`	Duplicate operation (e.g., adding GPIN already in pool)

Server Errors (5xx)

Status	Code	Meaning
500	`INTERNAL_ERROR`	Unexpected server error — contact support with request_id
503	`SERVICE_UNAVAILABLE`	Service temporarily unavailable — retry with backoff

TypeScript Error Handling

import { GenuineInClient, ApiError } from '@genuinein/sdk';

const client = new GenuineInClient({ apiKey: process.env.GENUINEIN_API_KEY });

try {
  const profile = await client.talent.getProfile('GPIN12345');
} catch (error) {
  if (error instanceof ApiError) {
    switch (error.code) {
      case 'AUTH_EXPIRED':
        // Refresh or rotate your API key
        await rotateApiKey();
        break;
      case 'RATE_LIMIT_EXCEEDED':
        // Wait and retry
        await sleep(error.details.reset_at - Date.now() / 1000);
        break;
      case 'NOT_FOUND':
        // Handle missing resource
        console.log(`Profile not found: ${error.message}`);
        break;
      default:
        // Log and alert
        console.error(`API Error [${error.code}]: ${error.message}`);
    }
  }
}

Python Error Handling

from genuinein import GenuineInClient, ApiError, RateLimitError

client = GenuineInClient(api_key=os.environ["GENUINEIN_API_KEY"])

try:
    profile = client.talent.get_profile("GPIN12345")
except RateLimitError as e:
    # Wait for rate limit reset
    time.sleep(e.retry_after)
    profile = client.talent.get_profile("GPIN12345")
except ApiError as e:
    if e.code == "NOT_FOUND":
        print(f"Profile not found: {e.message}")
    elif e.code == "FORBIDDEN":
        print(f"Permission denied: {e.message}")
    else:
        print(f"API error [{e.code}]: {e.message}")
        raise

Debugging Tips

Save the request_id — Include it in support tickets for fast resolution
Check the details field — Contains specific field errors and constraints
Use the /health endpoint — GET /api/enterprise/v1/health to verify service status
Test in sandbox mode — Set X-Sandbox: true to test without side effects
Enable SDK debug logging — Set debug: true in SDK config to see full request/response

Authentication API Reference