Error Reference

Complete error taxonomy and handling guide

2 min read

All KLOAKD SDKs share a consistent error hierarchy rooted at KloakdError.

Hierarchy

KloakdError
  AuthenticationError   (401)
  ForbiddenError        (403)  — org ID mismatch (IDOR protection)
  NotEntitledError      (403)  — plan doesn't include module
  RateLimitError        (429)
  UpstreamError         (502)
  ApiError              (other 4xx/5xx)

Handling errors

from kloakd.errors import AuthenticationError, RateLimitError, KloakdError

try:
    result = client.evadr.fetch("https://example.com")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except KloakdError as e:
    print(f"Error: {e}")

import { RateLimitError, KloakdError } from 'kloakd-sdk';

try {
  const result = await client.evadr.fetch('https://example.com');
} catch (e) {
  if (e instanceof RateLimitError) console.log('Retry after', e.retryAfter);
  else if (e instanceof KloakdError) console.log(e.message);
}

try {
    FetchResult r = client.evadr().fetch("https://example.com");
} catch (RateLimitException e) {
    System.out.printf("Retry after %ds%n", e.getRetryAfter());
} catch (KloakdException e) {
    System.out.println(e.getMessage());
}

Error fields

| Field | Type | Available on | |-------|------|-------------| | status_code | integer | All errors | | message | string | All errors | | retry_after | integer | RateLimitError only | | reset_at | string | RateLimitError only | | module | string | NotEntitledError only | | upgrade_url | string | NotEntitledError only | | expected_org | string | ForbiddenError only | | actual_org | string | ForbiddenError only |

Disable retries

client = Kloakd(api_key="...", organization_id="...", max_retries=0)

const client = new Kloakd({ apiKey: '...', organizationId: '...', maxRetries: 0 });

Kloakd client = Kloakd.builder().maxRetries(0).build();