API Error Codes

Fluxer uses standardized error codes to communicate specific error conditions. All API errors include a code field identifying the error type.

Error Response Format

API errors follow a consistent structure:

{
  "code": "UNKNOWN_CHANNEL",
  "message": "Unknown Channel",
  "errors": {
    "channel_id": {
      "_errors": [
        {
          "code": "UNKNOWN_CHANNEL",
          "message": "Unknown Channel"
        }
      ]
    }
  }
}

Response Fields

code

string

required

Machine-readable error code (e.g., UNKNOWN_CHANNEL)

message

string

required

Human-readable error message

errors

object

Field-specific validation errors (for validation errors)

HTTP Status Codes

Fluxer uses standard HTTP status codes:

Status	Name	Description
200	OK	Request succeeded
201	Created	Resource created successfully
204	No Content	Request succeeded with no response body
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Authenticated but not authorized
404	Not Found	Resource not found
409	Conflict	Resource conflict (e.g., duplicate)
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error
502	Bad Gateway	Gateway error
503	Service Unavailable	Service temporarily unavailable

General Errors

Authentication & Authorization

UNAUTHORIZED

HTTP Status: 401Missing or invalid authentication token.

{
  "code": "UNAUTHORIZED",
  "message": "Unauthorized"
}

FORBIDDEN

HTTP Status: 403Authenticated but lacking permission to access the resource.

{
  "code": "FORBIDDEN",
  "message": "Forbidden"
}

MISSING_PERMISSIONS

HTTP Status: 403Missing required permissions for the operation.

{
  "code": "MISSING_PERMISSIONS",
  "message": "Missing Permissions"
}

MISSING_ACCESS

HTTP Status: 403Not a member of the guild or lacking channel access.

{
  "code": "MISSING_ACCESS",
  "message": "Missing Access"
}

Resource Not Found

UNKNOWN_USER

HTTP Status: 404

{ "code": "UNKNOWN_USER", "message": "Unknown User" }

UNKNOWN_GUILD

HTTP Status: 404

{ "code": "UNKNOWN_GUILD", "message": "Unknown Guild" }

UNKNOWN_CHANNEL

HTTP Status: 404

{ "code": "UNKNOWN_CHANNEL", "message": "Unknown Channel" }

UNKNOWN_MESSAGE

HTTP Status: 404

{ "code": "UNKNOWN_MESSAGE", "message": "Unknown Message" }

UNKNOWN_MEMBER

HTTP Status: 404

{ "code": "UNKNOWN_MEMBER", "message": "Unknown Member" }

UNKNOWN_ROLE

HTTP Status: 404

{ "code": "UNKNOWN_ROLE", "message": "Unknown Role" }

Rate Limiting

RATE_LIMITED

HTTP Status: 429Rate limit exceeded. Includes retry information.

{
  "code": "RATE_LIMITED",
  "message": "You are being rate limited",
  "retry_after": 3.5,
  "global": false
}

Headers:

Retry-After: 4
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200000

SLOWMODE_RATE_LIMITED

HTTP Status: 429Channel slowmode prevents sending messages.

{
  "code": "SLOWMODE_RATE_LIMITED",
  "message": "You are sending messages too quickly",
  "retry_after": 5.0
}

Account Errors

Account Status

Code	Status	Description
`ACCOUNT_DISABLED`	403	Account has been disabled
`ACCOUNT_SUSPENDED_TEMPORARILY`	403	Account temporarily suspended
`ACCOUNT_SUSPENDED_PERMANENTLY`	403	Account permanently suspended
`ACCOUNT_SCHEDULED_FOR_DELETION`	403	Account pending deletion
`ACCOUNT_SUSPICIOUS_ACTIVITY`	403	Suspicious activity detected

Verification

Code	Status	Description
`EMAIL_VERIFICATION_REQUIRED`	403	Email verification required
`PHONE_VERIFICATION_REQUIRED`	403	Phone verification required
`GUILD_PHONE_VERIFICATION_REQUIRED`	403	Guild requires phone verification
`IP_AUTHORIZATION_REQUIRED`	403	New IP requires authorization
`TWO_FACTOR_REQUIRED`	403	Two-factor authentication required

OAuth2 Errors

Code	Status	Description
`INVALID_CLIENT`	401	Invalid OAuth2 client ID
`INVALID_CLIENT_SECRET`	401	Invalid client secret
`INVALID_GRANT`	400	Invalid authorization code or refresh token
`INVALID_SCOPE`	400	Invalid or unknown scope
`MISSING_OAUTH_SCOPE`	403	Missing required OAuth2 scope
`MISSING_OAUTH_ADMIN_SCOPE`	403	Missing admin scope
`INVALID_REDIRECT_URI`	400	Invalid redirect URI
`UNSUPPORTED_RESPONSE_TYPE`	400	Unsupported response type

Validation Errors

VALIDATION_ERROR

HTTP Status: 400Request validation failed. Includes field-specific errors.

{
  "code": "VALIDATION_ERROR",
  "message": "Validation Error",
  "errors": {
    "username": {
      "_errors": [
        {
          "code": "STRING_TYPE_TOO_SHORT",
          "message": "String must be at least 2 characters"
        }
      ]
    }
  }
}

Resource Limits

Guild Limits

Code	Description
`MAX_GUILDS`	Maximum guilds reached (100)
`MAX_GUILD_MEMBERS`	Guild member limit reached
`MAX_GUILD_CHANNELS`	Guild channel limit reached
`MAX_GUILD_ROLES`	Guild role limit reached (250)
`MAX_CATEGORY_CHANNELS`	Category channel limit reached

Channel Limits

Code	Description
`MAX_PINS_PER_CHANNEL`	Pin limit reached (50)
`MAX_WEBHOOKS_PER_CHANNEL`	Channel webhook limit reached
`MAX_INVITES`	Invite limit reached

User Limits

Code	Description
`MAX_FRIENDS`	Friend limit reached (1,000)
`MAX_GROUP_DMS`	Group DM limit reached
`MAX_GROUP_DM_RECIPIENTS`	Group DM recipient limit reached (10)
`MAX_BOOKMARKS`	Bookmark limit reached

Expression Limits

Code	Description
`MAX_EMOJIS`	Emoji limit reached
`MAX_ANIMATED_EMOJIS`	Animated emoji limit reached
`MAX_STICKERS`	Sticker limit reached
`MAX_REACTIONS`	Reaction limit reached (20 per message)

Message Errors

Code	Status	Description
`CANNOT_SEND_EMPTY_MESSAGE`	400	Message content is empty
`CANNOT_SEND_MESSAGES_TO_USER`	403	Cannot DM this user
`CANNOT_SEND_MESSAGES_IN_NON_TEXT_CHANNEL`	400	Wrong channel type
`CANNOT_EDIT_OTHER_USER_MESSAGE`	403	Cannot edit another user’s message
`FILE_SIZE_TOO_LARGE`	413	Attachment exceeds size limit
`MESSAGE_TOTAL_ATTACHMENT_SIZE_TOO_LARGE`	413	Total attachments exceed limit
`CONTENT_BLOCKED`	403	Message blocked by content filter
`EXPLICIT_CONTENT_CANNOT_BE_SENT`	403	Explicit content blocked

Permission Errors

Code	Status	Description
`INVALID_PERMISSIONS_INTEGER`	400	Invalid permission integer
`INVALID_PERMISSIONS_NEGATIVE`	400	Permissions cannot be negative
`MISSING_PERMISSIONS`	403	Missing required permissions

Channel Operation Errors

Code	Status	Description
`INVALID_CHANNEL_TYPE`	400	Invalid channel type
`INVALID_CHANNEL_TYPE_FOR_CALL`	400	Channel type doesn’t support calls
`CANNOT_EXECUTE_ON_DM`	400	Operation not allowed in DMs

Voice Errors

Code	Status	Description
`UNKNOWN_VOICE_REGION`	404	Unknown voice region
`UNKNOWN_VOICE_SERVER`	404	Unknown voice server
`VOICE_CHANNEL_FULL`	400	Voice channel is full
`USER_NOT_IN_VOICE`	400	User not in voice channel
`CANNOT_MODIFY_VOICE_STATE`	403	Cannot modify voice state
`NO_ACTIVE_CALL`	404	No active call in channel

Invite Errors

Code	Status	Description
`UNKNOWN_INVITE`	404	Invite code not found
`INVITES_DISABLED`	403	Invites disabled for guild
`USER_BANNED_FROM_GUILD`	403	User is banned
`USER_IP_BANNED_FROM_GUILD`	403	IP address is banned
`TEMPORARY_INVITE_REQUIRES_PRESENCE`	400	Temporary invites require presence

Connection Errors

Code	Status	Description
`CONNECTION_NOT_FOUND`	404	Connection not found
`CONNECTION_ALREADY_EXISTS`	409	Connection already exists
`CONNECTION_VERIFICATION_FAILED`	400	Connection verification failed
`CONNECTION_INVALID_TYPE`	400	Invalid connection type
`CONNECTION_INVALID_IDENTIFIER`	400	Invalid connection identifier
`CONNECTION_LIMIT_REACHED`	400	Connection limit reached

Payment Errors

Code	Status	Description
`STRIPE_ERROR`	400	Stripe payment error
`STRIPE_INVALID_PRODUCT`	400	Invalid product ID
`STRIPE_NO_ACTIVE_SUBSCRIPTION`	404	No active subscription
`PREMIUM_PURCHASE_BLOCKED`	403	Premium purchase blocked
`UNKNOWN_GIFT_CODE`	404	Gift code not found
`GIFT_CODE_ALREADY_REDEEMED`	400	Gift code already redeemed

Server Errors

Code	Status	Description
`INTERNAL_SERVER_ERROR`	500	Internal server error
`SERVICE_UNAVAILABLE`	503	Service temporarily unavailable
`BAD_GATEWAY`	502	Bad gateway
`GATEWAY_TIMEOUT`	504	Gateway timeout
`NOT_IMPLEMENTED`	501	Feature not implemented

Security Errors

Code	Status	Description
`CAPTCHA_REQUIRED`	400	CAPTCHA verification required
`INVALID_CAPTCHA`	400	Invalid CAPTCHA response
`IP_BANNED`	403	IP address is banned
`SUDO_MODE_REQUIRED`	403	Sudo mode required for operation
`INVALID_SUDO_TOKEN`	401	Invalid sudo token

WebAuthn Errors

Code	Status	Description
`PASSKEYS_DISABLED`	403	Passkeys disabled
`NO_PASSKEYS_REGISTERED`	404	No passkeys registered
`PASSKEY_AUTHENTICATION_FAILED`	401	Passkey authentication failed
`UNKNOWN_WEBAUTHN_CREDENTIAL`	404	Unknown WebAuthn credential
`INVALID_WEBAUTHN_CREDENTIAL`	400	Invalid credential
`WEBAUTHN_CREDENTIAL_LIMIT_REACHED`	400	Credential limit reached

Handling Errors

TypeScript

import { FluxerError } from '@fluxer/errors';

try {
  await sendMessage(channelId, content);
} catch (error) {
  if (error instanceof FluxerError) {
    console.log(`Error ${error.code}: ${error.message}`);
    console.log(`HTTP Status: ${error.status}`);
  }
}

Checking Specific Errors

import { UnknownChannelError } from '@fluxer/errors';

try {
  const channel = await getChannel(channelId);
} catch (error) {
  if (error instanceof UnknownChannelError) {
    console.log('Channel not found');
  }
}

API Client

const response = await fetch('/api/channels/123/messages', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}` },
  body: JSON.stringify({ content: 'Hello!' })
});

if (!response.ok) {
  const error = await response.json();
  
  switch (error.code) {
    case 'RATE_LIMITED':
      await new Promise(r => setTimeout(r, error.retry_after * 1000));
      break;
    case 'MISSING_PERMISSIONS':
      console.log('Insufficient permissions');
      break;
    case 'UNKNOWN_CHANNEL':
      console.log('Channel not found');
      break;
  }
}

Best Practices

Check Error Codes

Always check the code field, not just the HTTP status or message text.

Handle Rate Limits

Implement exponential backoff for rate limit errors using the retry_after field.

Log Full Errors

Log the complete error response for debugging, not just the message.

User-Friendly Messages

Translate error codes into user-friendly messages in your UI.

Get Started

Core Features

Self-Hosting

Bot Development

WebSocket Gateway

Topics

Resources

​Error Response Format

​Response Fields

​HTTP Status Codes

​General Errors

​Authentication & Authorization

​Resource Not Found

​Rate Limiting

​Account Errors

​Account Status

​Verification

​OAuth2 Errors

​Validation Errors

​Resource Limits

​Guild Limits

​Channel Limits

​User Limits

​Expression Limits

​Message Errors

​Permission Errors

​Channel Operation Errors

​Voice Errors

​Invite Errors

​Connection Errors

​Payment Errors

​Server Errors

​Security Errors

​WebAuthn Errors

​Handling Errors

​TypeScript

​Checking Specific Errors

​API Client

​Best Practices

Check Error Codes

Handle Rate Limits

Log Full Errors

User-Friendly Messages

Build docs developers (and LLMs) love

Error Response Format

Response Fields

HTTP Status Codes

General Errors

Authentication & Authorization

Resource Not Found

Rate Limiting

Account Errors

Account Status

Verification

OAuth2 Errors

Validation Errors

Resource Limits

Guild Limits

Channel Limits

User Limits

Expression Limits

Message Errors

Permission Errors

Channel Operation Errors

Voice Errors

Invite Errors

Connection Errors

Payment Errors

Server Errors

Security Errors

WebAuthn Errors

Handling Errors

TypeScript

Checking Specific Errors

API Client

Best Practices