Error Codes

Reference of all error types returned by CORTEX.

Authentication Errors

invalid-credentials

{
  "type": "https://api.cortex.purplelab.ai/errors/invalid-credentials",
  "title": "Invalid Credentials",
  "status": 401,
  "detail": "The email or password provided is incorrect"
}

account-locked

{
  "type": "https://api.cortex.purplelab.ai/errors/account-locked",
  "title": "Account Locked",
  "status": 403,
  "detail": "Account is temporarily locked due to too many failed login attempts"
}

account-suspended

{
  "type": "https://api.cortex.purplelab.ai/errors/account-suspended",
  "title": "Account Suspended",
  "status": 403,
  "detail": "This account has been suspended"
}

invalid-token

{
  "type": "https://api.cortex.purplelab.ai/errors/invalid-token",
  "title": "Invalid Token",
  "status": 401,
  "detail": "The access token is invalid or has expired"
}

token-expired

{
  "type": "https://api.cortex.purplelab.ai/errors/token-expired",
  "title": "Token Expired",
  "status": 401,
  "detail": "The access token has expired. Please refresh your token."
}

Validation Errors

validation-error

{
  "type": "https://api.cortex.purplelab.ai/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "One or more fields failed validation",
  "errors": [
    { "field": "email", "message": "must be a valid email" }
  ]
}

invalid-uuid

{
  "type": "https://api.cortex.purplelab.ai/errors/invalid-uuid",
  "title": "Invalid UUID",
  "status": 400,
  "detail": "The provided ID is not a valid UUID"
}

password-policy

{
  "type": "https://api.cortex.purplelab.ai/errors/password-policy",
  "title": "Password Policy Violation",
  "status": 400,
  "detail": "Password must contain at least one uppercase letter"
}

Authorization Errors

unauthorized

{
  "type": "https://api.cortex.purplelab.ai/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication is required to access this resource"
}

forbidden

{
  "type": "https://api.cortex.purplelab.ai/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "You do not have permission to perform this action"
}

insufficient-permissions

{
  "type": "https://api.cortex.purplelab.ai/errors/insufficient-permissions",
  "title": "Insufficient Permissions",
  "status": 403,
  "detail": "Required permission: users:create"
}

Resource Errors

not-found

{
  "type": "https://api.cortex.purplelab.ai/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested resource was not found"
}

conflict

{
  "type": "https://api.cortex.purplelab.ai/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A user with this email already exists"
}

resource-in-use

{
  "type": "https://api.cortex.purplelab.ai/errors/resource-in-use",
  "title": "Resource In Use",
  "status": 409,
  "detail": "Cannot delete role: it has active assignments"
}

Rate Limiting

rate-limit-exceeded

{
  "type": "https://api.cortex.purplelab.ai/errors/rate-limit-exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Try again in 45 seconds.",
  "retryAfter": 45
}

Server Errors

internal-error

{
  "type": "https://api.cortex.purplelab.ai/errors/internal-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred"
}

service-unavailable

{
  "type": "https://api.cortex.purplelab.ai/errors/service-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "The service is temporarily unavailable"
}

Error Type Reference

Type	Status	Category
invalid-credentials	401	Authentication
account-locked	403	Authentication
account-suspended	403	Authentication
invalid-token	401	Authentication
token-expired	401	Authentication
validation-error	400	Validation
invalid-uuid	400	Validation
password-policy	400	Validation
unauthorized	401	Authorization
forbidden	403	Authorization
insufficient-permissions	403	Authorization
not-found	404	Resource
conflict	409	Resource
resource-in-use	409	Resource
rate-limit-exceeded	429	Rate Limiting
internal-error	500	Server
service-unavailable	503	Server