Error Codes

When something goes wrong, Velox TS returns structured error responses with HTTP status codes and machine-readable error codes. This reference covers every status code and error code your API can return, along with common causes and how to handle them on the client.

HTTP Status Codes

Success (2xx)

Code	Name	Usage
`200`	OK	Successful GET, PUT, PATCH, DELETE
`201`	Created	Successful POST (resource created)
`204`	No Content	Successful DELETE (no body)

Client Errors (4xx)

Code	Name	Usage
`400`	Bad Request	Invalid input, validation failed
`401`	Unauthorized	Missing or invalid authentication
`403`	Forbidden	Authenticated but not authorized
`404`	Not Found	Resource doesn’t exist
`409`	Conflict	Resource already exists (e.g., duplicate email)
`422`	Unprocessable Entity	Semantic validation errors
`429`	Too Many Requests	Rate limit exceeded

Server Errors (5xx)

Code	Name	Usage
`500`	Internal Server Error	Unexpected server error
`502`	Bad Gateway	Upstream service error
`503`	Service Unavailable	Server overloaded or maintenance

Error Response Format

Velox TS returns errors in a consistent format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

Application Error Codes

Validation Errors

Code	HTTP	Description
`VALIDATION_ERROR`	400	Input validation failed
`INVALID_INPUT`	400	Malformed request body
`MISSING_FIELD`	400	Required field not provided
`INVALID_FORMAT`	400	Field format incorrect

Authentication Errors

Code	HTTP	Description
`UNAUTHENTICATED`	401	No valid auth token
`TOKEN_EXPIRED`	401	Access token expired
`INVALID_TOKEN`	401	Token malformed or invalid
`REFRESH_TOKEN_EXPIRED`	401	Refresh token expired
`SESSION_EXPIRED`	401	Session no longer valid

Authorization Errors

Code	HTTP	Description
`FORBIDDEN`	403	Action not permitted
`INSUFFICIENT_PERMISSIONS`	403	Missing required permission
`ROLE_REQUIRED`	403	Missing required role

Resource Errors

Code	HTTP	Description
`NOT_FOUND`	404	Resource doesn’t exist
`ALREADY_EXISTS`	409	Duplicate resource
`CONFLICT`	409	State conflict

Rate Limiting

Code	HTTP	Description
`RATE_LIMITED`	429	Too many requests
`QUOTA_EXCEEDED`	429	Usage quota exceeded

Handling Errors

In Procedures

import { TRPCError } from '@trpc/server';

export const getUser = procedure()
  .input(z.object({ id: z.string() }))
  .query(async ({ input, ctx }) => {
    const user = await ctx.db.user.findUnique({
      where: { id: input.id },
    });

    if (!user) {
      throw new TRPCError({
        code: 'NOT_FOUND',
        message: 'User not found',
      });
    }

    return user;
  });

Custom Error Classes

import { VeloxError, NotFoundError } from '@veloxts/core';

// Use built-in error classes for common cases
throw new NotFoundError('User', input.id);
// Message: "User with id {id} not found"

// Or create custom domain errors
throw new VeloxError('User account is suspended', 403, 'USER_SUSPENDED');

Client-Side Handling

import { client } from './api';

try {
  const user = await client.users.getUser.query({ id: '123' });
} catch (error) {
  if (error.data?.code === 'NOT_FOUND') {
    // Handle not found
  } else if (error.data?.code === 'UNAUTHENTICATED') {
    // Redirect to login
  }
}

tRPC Error Codes

Velox TS uses tRPC error codes internally:

tRPC Code	HTTP	Description
`BAD_REQUEST`	400	Invalid request
`UNAUTHORIZED`	401	Not authenticated
`FORBIDDEN`	403	Not authorized
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	Resource conflict
`PARSE_ERROR`	400	JSON parse error
`INTERNAL_SERVER_ERROR`	500	Server error

Troubleshooting - Common issues
Error Handling - Error handling patterns