HTTP Status Codes

Complete reference for all HTTP status codes returned by the KLOAKD API

3 min read

The KLOAKD API uses standard HTTP status codes. All error responses include a JSON body with error, message, and request_id fields.

2xx - Success

| Code | Meaning | When returned | |------|---------|---------------| | 200 OK | Request succeeded | Successful GET, POST responses | | 202 Accepted | Job enqueued | Async job creation (returns job_id) |

4xx - Client Errors

| Code | Meaning | When returned | |------|---------|---------------| | 400 Bad Request | Invalid request body or parameters | Missing required fields, malformed JSON | | 401 Unauthorized | Missing or invalid API key | No Authorization header, expired key | | 403 Forbidden | Valid key, insufficient entitlements or org ID mismatch | Module not in your plan; or the org_id in the URL does not match your API key's organization (IDOR protection) | | 404 Not Found | Resource does not exist | Job ID not found, unknown endpoint | | 409 Conflict | Duplicate request | Idempotency key already used | | 422 Unprocessable Entity | Validation failed | URL format invalid, unsupported target | | 429 Too Many Requests | Rate limit exceeded | See Retry-After response header |

5xx - Server Errors

| Code | Meaning | When returned | |------|---------|---------------| | 500 Internal Server Error | Unexpected server fault | Bug - contact support with request_id | | 502 Bad Gateway | Upstream target unreachable | Target site blocked the request | | 503 Service Unavailable | API temporarily unavailable | Maintenance window or overload | | 504 Gateway Timeout | Upstream response too slow | Target site took too long to respond |

Error response body

{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded 1000 requests per minute.",
  "request_id": "req_01HX4K9P3VFQJ2M8RNVT6BWYS",
  "retry_after": 42
}

Retry behaviour

All SDKs retry 429 and 5xx responses with exponential backoff by default.

| Attempt | Delay | |---------|-------| | 1st retry | 500ms | | 2nd retry | 1s | | 3rd retry | 2s |

Configure via max_retries (default 3):

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

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

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

Rate limit headers

Every response includes:

| Header | Description | |--------|-------------| | X-RateLimit-Limit | Requests allowed per window | | X-RateLimit-Remaining | Requests left in current window | | X-RateLimit-Reset | Unix timestamp when the window resets | | Retry-After | Seconds to wait (only on 429) |