Error Codes

This document provides a comprehensive list of all error codes used in the WebmixHub API, organized by module. Each error code includes its HTTP status code, message, and description.

General HTTP Errors

These are standard HTTP error codes that can occur across different endpoints.

Code	HTTP Status	Message	Description
BAD_REQUEST	400	Bad Request	The request is malformed or contains invalid parameters
UNAUTHORIZED	401	Unauthorized	Authentication required or authentication failed
FORBIDDEN	403	Forbidden	The request is valid, but the user doesn't have permission
NOT_FOUND	404	Not Found	The requested resource does not exist
CONFLICT	409	Conflict	The request conflicts with the current state of the resource
UNPROCESSABLE_ENTITY	422	Unprocessable Entity	The request is well-formed but contains semantic errors
TOO_MANY_REQUESTS	429	Too Many Requests	Rate limit exceeded. Too many requests in a given time period
INTERNAL_SERVER	500	Internal Server Error	An unexpected error occurred on the server
SERVICE_UNAVAILABLE	503	Service Unavailable	The service is temporarily unavailable
REQUEST_TIMEOUT	408	Request Timeout	The request took too long to process

Validation Errors

Validation errors are returned with the VALIDATION_ERROR code (which maps to BAD_REQUEST status) and include detailed field-level validation messages in the validation object.

Code	HTTP Status	Message	Description
VALIDATION_ERROR	400	The request could not be processed	Request validation failed with field-level errors

Auth Module

Errors related to authentication and authorization operations.

Code	HTTP Status	Message	Description
INVALID_CREDENTIALS	401	Invalid credentials	The provided credentials (email/password) are incorrect
INVALID_REFRESH_TOKEN	401	Invalid refresh token	The refresh token is invalid, expired, or has been revoked
MISSING_TENANT_TOKEN	401	Missing tenant token	Tenant authentication token is missing from the request
MISSING_USER_TOKEN	401	Missing user token	User authentication token is missing from the request
INVALID_TENANT_TOKEN	401	Invalid tenant token	Tenant authentication token is invalid or malformed
INVALID_USER_TOKEN	401	Invalid user token	User authentication token is invalid or malformed
TOKEN_USER_NOT_FOUND	401	Token user not found	The user referenced in the token does not exist
USER_ALREADY_EXISTS	409	User already exists	A user with the provided email already exists
RESTRICTED_CAPABILITY	403	Capability is restricted	The requested capability is not allowed for the specified authentication method
RESET_PASSWORD_USER_NOT_FOUND	409	Reset password user not found	User attempting to reset password was not found or does not use password authentication
EXTERNAL_SERVICE_ERROR	500	External service error	An error occurred while communicating with an external service

OTP Module

Errors related to One-Time Password operations.

Code	HTTP Status	Message	Description
OTP_NOT_FOUND	404	OTP not found	The OTP with the provided ID and scope does not exist
OTP_METHOD_NOT_ALLOWED	422	OTP method not allowed	The requested OTP method is not allowed for the specified scope
OTP_NOT_PENDING	422	OTP is not pending	OTP is not in a pending state (may already be verified, consumed, expired, failed, or cancelled)
OTP_EXPIRED	422	OTP has expired	The OTP has passed its expiration time
OTP_CODE_INCORRECT	422	OTP code is incorrect	The provided OTP code does not match (attempt count is incremented)
OTP_MAX_ATTEMPTS	422	OTP has reached the maximum number of attempts	The maximum number of verification attempts has been reached (status changed to failed)
OTP_RESEND_INTERVAL_NOT_EXPIRED	422	OTP resend interval not expired	The required time interval between resends has not yet passed
OTP_MAX_RESENDS_REACHED	422	OTP has reached the maximum number of resends	The maximum number of resends has been reached
OTP_NOT_CANCELABLE	422	OTP is not cancelable	The OTP cannot be cancelled (not in a pending state)
OTP_NOT_CONSUMABLE	422	OTP is not consumable	The OTP cannot be consumed (must be verified first or is in an invalid state)
OTP_ALREADY_CONSUMED	422	OTP already consumed	The OTP has already been consumed
OTP_CONSUME_CALLBACK_ERROR	500	OTP consume callback error	An error occurred during the OTP consumption callback

Tenant Configuration Module

Errors related to tenant configuration.

Code	HTTP Status	Message	Description
TENANT_NOT_CONFIGURED	500	Tenant configuration is not configured	The tenant configuration for the requested service is missing or invalid

Common Runtime Errors

General runtime errors that can occur in various contexts.

Code	HTTP Status	Message	Description
UNEXPECTED_STATE	500	Unexpected state	The system is in an unexpected state that should not occur

Error Response Format

All error responses follow this structure:

{
  "meta": {
    "requestId": "string",
    "timestamp": "ISO 8601 date string"
  },
  "error": {
    "message": "Human-readable error message",
    "code": "ERROR_CODE",
    "status": 400,
    "validation": {}, // Optional: field-level validation errors
    "detail": {} // Optional: additional error information
  }
}

Notes

• Error codes are machine-readable identifiers that can be used for programmatic error handling
• The detail field structure varies based on the error code and may contain additional context