Error Codes
Comprehensive list of CODITECT API error codes and how to resolve them.
Error Response Format
All errors follow this structure:
{
"error": {
"code": "error_code",
"message": "Human-readable description",
"details": {
// Additional context
}
},
"meta": {
"request_id": "req_abc123"
}
}
Authentication Errors
invalid_credentials
HTTP Status: 401
The email/password combination is incorrect.
{
"error": {
"code": "invalid_credentials",
"message": "The email or password is incorrect"
}
}
Resolution: Verify credentials or reset password.
token_expired
HTTP Status: 401
The access token has expired.
{
"error": {
"code": "token_expired",
"message": "The access token has expired",
"details": {
"expired_at": "2026-01-09T10:00:00Z"
}
}
}
Resolution: Use refresh token to obtain new access token.
token_invalid
HTTP Status: 401
The token is malformed or has been revoked.
{
"error": {
"code": "token_invalid",
"message": "The access token is invalid"
}
}
Resolution: Re-authenticate to obtain new tokens.
insufficient_scope
HTTP Status: 403
The token doesn't have required permissions.
{
"error": {
"code": "insufficient_scope",
"message": "This action requires the 'write:projects' scope",
"details": {
"required_scope": "write:projects",
"current_scopes": ["read:projects"]
}
}
}
Resolution: Request a token with required scopes.
License Errors
no_seats_available
HTTP Status: 409
All license seats are currently in use.
{
"error": {
"code": "no_seats_available",
"message": "All seats are currently in use (10/10)",
"details": {
"max_seats": 10,
"active_seats": 10,
"next_available_hint": "2026-01-09T10:30:00Z"
}
}
}
Resolution: Wait for a seat to be released or upgrade license.
license_expired
HTTP Status: 403
The license has passed its expiration date.
{
"error": {
"code": "license_expired",
"message": "This license expired on 2026-01-01",
"details": {
"expired_at": "2026-01-01T00:00:00Z",
"license_id": "lic_abc123"
}
}
}
Resolution: Renew subscription or contact support.
license_suspended
HTTP Status: 403
The license has been suspended (usually due to payment issues).
{
"error": {
"code": "license_suspended",
"message": "License suspended due to payment failure",
"details": {
"reason": "payment_failed",
"suspended_at": "2026-01-05T00:00:00Z"
}
}
}
Resolution: Update payment method and retry.
session_timeout
HTTP Status: 410
The session expired due to missed heartbeats.
{
"error": {
"code": "session_timeout",
"message": "Session expired due to missed heartbeat",
"details": {
"last_heartbeat": "2026-01-09T10:00:00Z",
"timeout_at": "2026-01-09T10:06:00Z"
}
}
}
Resolution: Acquire a new session.
invalid_hardware_id
HTTP Status: 400
The hardware ID format is invalid or unrecognized.
{
"error": {
"code": "invalid_hardware_id",
"message": "The hardware ID format is invalid",
"details": {
"provided": "invalid-id",
"expected_format": "hw_[a-z0-9]{32}"
}
}
}
Resolution: Use the SDK to generate valid hardware ID.
Validation Errors
validation_error
HTTP Status: 422
Request body failed validation.
{
"error": {
"code": "validation_error",
"message": "Request validation failed",
"details": {
"errors": [
{
"field": "email",
"message": "Must be a valid email address"
},
{
"field": "password",
"message": "Must be at least 12 characters"
}
]
}
}
}
Resolution: Fix the indicated fields and retry.
invalid_request
HTTP Status: 400
The request is malformed.
{
"error": {
"code": "invalid_request",
"message": "Invalid JSON in request body",
"details": {
"parse_error": "Unexpected token at position 45"
}
}
}
Resolution: Verify request format and content type.
Resource Errors
not_found
HTTP Status: 404
The requested resource doesn't exist.
{
"error": {
"code": "not_found",
"message": "Project not found",
"details": {
"resource_type": "project",
"resource_id": "proj_xyz789"
}
}
}
Resolution: Verify the resource ID exists.
already_exists
HTTP Status: 409
A resource with this identifier already exists.
{
"error": {
"code": "already_exists",
"message": "A project with this name already exists",
"details": {
"field": "name",
"value": "my-project"
}
}
}
Resolution: Use a different identifier.
Rate Limiting Errors
rate_limit_exceeded
HTTP Status: 429
Too many requests in the time window.
{
"error": {
"code": "rate_limit_exceeded",
"message": "Too many requests",
"details": {
"limit": 300,
"window": "1 minute",
"retry_after": 45
}
}
}
Resolution: Wait for Retry-After seconds before retrying.
Server Errors
internal_error
HTTP Status: 500
An unexpected error occurred.
{
"error": {
"code": "internal_error",
"message": "An internal error occurred",
"details": {
"request_id": "req_abc123"
}
}
}
Resolution: Retry the request. If persistent, contact support with request_id.
service_unavailable
HTTP Status: 503
The service is temporarily unavailable.
{
"error": {
"code": "service_unavailable",
"message": "Service temporarily unavailable",
"details": {
"retry_after": 30
}
}
}
Resolution: Wait and retry. Check status.coditect.ai.
Error Handling Example
from coditect import Client
from coditect.exceptions import (
CoditectError,
AuthenticationError,
RateLimitError,
LicenseError,
ValidationError
)
client = Client(api_key="cdt_live_xxx...")
try:
session = client.licenses.acquire(
license_key="CODI-XXXX-XXXX-XXXX",
hardware_id="hw_abc123"
)
except AuthenticationError as e:
print(f"Auth failed: {e.message}")
# Re-authenticate
except RateLimitError as e:
print(f"Rate limited. Retry after {e.retry_after} seconds")
time.sleep(e.retry_after)
except LicenseError as e:
if e.code == "no_seats_available":
print("All seats in use. Try again later.")
elif e.code == "license_expired":
print("License expired. Please renew.")
except ValidationError as e:
for error in e.errors:
print(f"Field '{error.field}': {error.message}")
except CoditectError as e:
print(f"Error {e.code}: {e.message}")
print(f"Request ID: {e.request_id}")
Getting Help
When contacting support, include:
- Request ID from the error response
- Error code and message
- Request details (endpoint, method, sanitized body)
- Timestamp when error occurred
Email: 1@az1.ai