Skip to main content
Internal Documentation Only: If you’re not a Null Tools developer, you can close this documentation or visit the Apps section to learn more about using Null Pass in your applications.

​
Error Response Format

All errors follow a consistent format: 
{
  "error": "Error message description"
}

​
Status Codes

​
200
OK
Request successful
​
201
Created
Resource created successfully (e.g., user registration)
​
400
Bad Request
Validation error or invalid request format
  • Missing required fields
  • Invalid data format
  • Validation rule violations (e.g., password too short)
​
401
Unauthorized
Authentication required or failed
  • Missing Authorization header
  • Invalid or expired token
  • Invalid credentials
  • Invalid 2FA code
​
403
Forbidden
Request blocked by security system
  • Rate limit exceeded (Arcjet)
  • Bot detected (Arcjet)
  • Shield protection triggered
​
404
Not Found
Resource not found
  • User not found
  • Session not found
  • Invalid endpoint
​
409
Conflict
Resource conflict
  • User already exists
  • Duplicate resource
​
500
Internal Server Error
Server error
  • Database error
  • Unexpected exception
  • Configuration error

​
Common Error Scenarios

​
Validation Errors (400)

{
  "error": "Password must be at least 8 characters"
}
Causes:
  • Invalid email format
  • Password too short
  • Missing required fields
  • Invalid data types

​
Authentication Errors (401)

{
  "error": "Invalid credentials"
}
Causes:
  • Wrong email/password
  • Expired token
  • Invalid 2FA code
  • Missing Authorization header

​
Rate Limit Errors (403)

{
  "error": "Rate limit exceeded"
}
Causes:
  • Too many requests in short time
  • Bot detection triggered
  • Shield protection activated

​
Not Found Errors (404)

{
  "error": "User not found"
}
Causes:
  • Invalid user ID
  • Resource deleted
  • Invalid endpoint path

​
Error Handling Best Practices

try {
  const response = await fetch('/api/auth/login', {
    method: 'POST',
    body: JSON.stringify({ email, password })
  });
  
  if (!response.ok) {
    const error = await response.json();
    // Handle specific error types
    if (response.status === 401) {
      // Invalid credentials
    } else if (response.status === 403) {
      // Rate limited
    } else if (response.status === 400) {
      // Validation error
    }
    throw new Error(error.error);
  }
  
  const data = await response.json();
} catch (error) {
  // Handle network or parsing errors
}
Implement exponential backoff for:
  • 500 errors (server errors)
  • 403 errors (rate limits)
  • Network failures
Don’t retry:
  • 400 errors (validation - fix request)
  • 401 errors (authentication - re-authenticate)
  • 404 errors (not found - check resource)
Log all errors with:
  • Error message
  • Status code
  • Request details (without sensitive data)
  • Timestamp
  • User ID (if authenticated)

​
Internal Error Logging

Errors are logged server-side with different levels:
  • Warn: Validation errors, failed auth attempts
  • Error: Server errors, unexpected exceptions
  • Info: Successful operations, important events
Check application logs for detailed error information including stack traces for 500 errors.