Error Codes & Troubleshooting

Complete reference for all ZendBX error codes with solutions.

Error Response Format

All errors follow this consistent format:

json

{
  "error": {
    "message": "Human-readable error description",
    "status": 400,
    "code": "INVALID_REQUEST",
    "details": {
      // Additional context
    }
  },
  "data": null
}

4xx Client Errors

400 Bad Request

The request was malformed or missing required parameters.

Common Causes:

Missing required fields in request body
Invalid JSON syntax
Invalid UUID format for projectId
Malformed query parameters

Solution:

typescript

// ❌ Wrong - missing required field
await db.from('users').insert({ name: 'John' }) // email required

// ✅ Correct
await db.from('users').insert({ name: 'John', email: 'john@example.com' })

401 Unauthorized

Missing or invalid authentication token.

Common Causes:

No Authorization header
Expired JWT token
Invalid API key
Token signed with wrong secret

Solution:

typescript

// Check if user is signed in
const { data: { user } } = await db.auth.getUser()
if (!user) {
  // Redirect to login
  window.location.href = '/login'
}

// Or sign in again
await db.auth.signIn({ email, password })

403 Forbidden

Authenticated but not authorized to perform this action.

Common Causes:

Row Level Security policy denied access
Insufficient permissions for the project
Trying to access another user's data
Using anon key for admin operations

Solution:

sql

// Check RLS policies in dashboard
// Ensure policy allows current user:
CREATE POLICY "Users can read own data"
ON users FOR SELECT
USING (auth.uid() = id);

// Or use service_role key on server (bypasses RLS)
const serverClient = createClient({
  apiUrl, projectId,
  anonKey: process.env.ZENDBX_SERVICE_KEY
})

404 Not Found

The requested resource doesn't exist.

Common Causes:

Table doesn't exist
Bucket doesn't exist
File not found
Wrong project slug in URL

Solution:

typescript

// Verify table exists
const { data: tables } = await db.db.listTables()
console.log(tables)

// Check bucket exists
const { data: buckets } = await db.storage.listBuckets()
console.log(buckets)

409 Conflict

Unique constraint violation or duplicate key.

Common Causes:

Email already exists (signup)
Duplicate primary key
Unique constraint violation

Solution:

typescript

// Check if exists before insert
const { data: existing } = await db
  .from('users')
  .select('email')
  .eq('email', email)
  .single()

if (existing) {
  alert('Email already registered')
} else {
  await db.from('users').insert({ email, ... })
}

429 Too Many Requests

Rate limit exceeded.

Rate Limits:

Free tier: 100 requests/minute
Pro tier: 1000 requests/minute
Enterprise: Custom limits

Solution:

typescript

// Implement exponential backoff
async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn()
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, 1000 * (2 ** i)))
        continue
      }
      throw error
    }
  }
}

5xx Server Errors

500 Internal Server Error

Unexpected server error.

Common Causes:

Database connection failed
Invalid SQL syntax
Server misconfiguration

Solution:

Retry the request
Check server status at status.zendbx.in
Contact support if persistent

503 Service Unavailable

Service temporarily unavailable (maintenance or overload).

Solution:

Wait 30-60 seconds and retry
Check status.zendbx.in
Subscribe to status notifications

Specific Error Messages

"relation does not exist"

Table doesn't exist in your database.

typescript

// Create the table first in Dashboard → Database → Tables
// Or programmatically:
await db.db.createTable('todos', [
  { name: 'id', type: 'uuid', primary_key: true },
  { name: 'title', type: 'text' },
])

"column does not exist"

You're selecting/updating a column that doesn't exist.

typescript

// Check table schema
const { data: schema } = await db.db.getTable('users')
console.log(schema.columns)

"Missing projectId"

Client initialized without required projectId.

typescript

// ❌ Wrong
const db = createClient({ apiUrl, anonKey })

// ✅ Correct
const db = createClient({ apiUrl, anonKey, projectId: 'your-project-id' })

"CORS policy blocked"

Your domain isn't allowed in CORS settings.

Solution: Add your domain in Dashboard → Settings → CORS

"WebSocket connection failed"

Can't connect to realtime server.

typescript

// Check WebSocket server is running
// Default: ws://localhost:8001

// Or specify custom URL:
const db = createClient({
  apiUrl, anonKey, projectId,
  wsUrl: 'wss://ws.zendbx.in'
})

Debugging Tips

Check browser console — Full error details appear in DevTools
Enable debug logging — Set DEBUG=zendbx:*
Test with cURL — Isolate SDK vs API issues
Verify credentials — Double-check URL, project ID, and API keys
Check RLS policies — Use service key to bypass RLS temporarily

Need Help?

Join our Discord community or email support@zendbx.in

4xx Client Errors

400 Bad Request

The request was malformed or missing required parameters.

Common Causes:

Missing required fields in request body
Invalid JSON syntax
Invalid UUID format for projectId
Malformed query parameters

Solution:

typescript

// ❌ Wrong - missing required field
await db.from('users').insert({ name: 'John' }) // email required

// ✅ Correct
await db.from('users').insert({ name: 'John', email: 'john@example.com' })

401 Unauthorized

Missing or invalid authentication token.

Common Causes:

No Authorization header
Expired JWT token
Invalid API key
Token signed with wrong secret

Solution:

typescript

// Check if user is signed in
const { data: { user } } = await db.auth.getUser()
if (!user) {
  // Redirect to login
  window.location.href = '/login'
}

// Or sign in again
await db.auth.signIn({ email, password })

403 Forbidden

Authenticated but not authorized to perform this action.

Common Causes:

Row Level Security policy denied access
Insufficient permissions for the project
Trying to access another user's data
Using anon key for admin operations

Solution:

sql

// Check RLS policies in dashboard
// Ensure policy allows current user:
CREATE POLICY "Users can read own data"
ON users FOR SELECT
USING (auth.uid() = id);

// Or use service_role key on server (bypasses RLS)
const serverClient = createClient({
  apiUrl, projectId,
  anonKey: process.env.ZENDBX_SERVICE_KEY
})

404 Not Found

The requested resource doesn't exist.

Common Causes:

Table doesn't exist
Bucket doesn't exist
File not found
Wrong project slug in URL

Solution:

typescript

// Verify table exists
const { data: tables } = await db.db.listTables()
console.log(tables)

// Check bucket exists
const { data: buckets } = await db.storage.listBuckets()
console.log(buckets)

409 Conflict

Unique constraint violation or duplicate key.

Common Causes:

Email already exists (signup)
Duplicate primary key
Unique constraint violation

Solution:

typescript

// Check if exists before insert
const { data: existing } = await db
  .from('users')
  .select('email')
  .eq('email', email)
  .single()

if (existing) {
  alert('Email already registered')
} else {
  await db.from('users').insert({ email, ... })
}

429 Too Many Requests

Rate limit exceeded.

Rate Limits:

Free tier: 100 requests/minute
Pro tier: 1000 requests/minute
Enterprise: Custom limits

Solution:

typescript

// Implement exponential backoff
async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn()
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, 1000 * (2 ** i)))
        continue
      }
      throw error
    }
  }
}

5xx Server Errors

500 Internal Server Error

Unexpected server error.

Common Causes:

Database connection failed
Invalid SQL syntax
Server misconfiguration

Solution:

Retry the request
Check server status at status.zendbx.in
Contact support if persistent

503 Service Unavailable

Service temporarily unavailable (maintenance or overload).

Solution:

Wait 30-60 seconds and retry
Check status.zendbx.in
Subscribe to status notifications

Specific Error Messages

"relation does not exist"

Table doesn't exist in your database.

typescript

// Create the table first in Dashboard → Database → Tables
// Or programmatically:
await db.db.createTable('todos', [
  { name: 'id', type: 'uuid', primary_key: true },
  { name: 'title', type: 'text' },
])

"column does not exist"

You're selecting/updating a column that doesn't exist.

typescript

// Check table schema
const { data: schema } = await db.db.getTable('users')
console.log(schema.columns)

"Missing projectId"

Client initialized without required projectId.

typescript

// ❌ Wrong
const db = createClient({ apiUrl, anonKey })

// ✅ Correct
const db = createClient({ apiUrl, anonKey, projectId: 'your-project-id' })

"CORS policy blocked"

Your domain isn't allowed in CORS settings.

Solution: Add your domain in Dashboard → Settings → CORS

"WebSocket connection failed"

Can't connect to realtime server.

typescript

// Check WebSocket server is running
// Default: ws://localhost:8001

// Or specify custom URL:
const db = createClient({
  apiUrl, anonKey, projectId,
  wsUrl: 'wss://ws.zendbx.in'
})

Debugging Tips

Check browser console — Full error details appear in DevTools

Enable debug logging — Set DEBUG=zendbx:*

Test with cURL — Isolate SDK vs API issues

Verify credentials — Double-check URL, project ID, and API keys

Check RLS policies — Use service key to bypass RLS temporarily