Error Codes

Complete reference of API error codes, their meanings, and how to resolve them.

HTTP Status Codes

Success Codes

Code	Name	Description
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`204`	No Content	Request succeeded, no content to return

Client Error Codes

Code	Name	Common Causes
`400`	Bad Request	Invalid input, malformed JSON, validation error
`401`	Unauthorized	Missing or invalid authentication token
`403`	Forbidden	Valid token but insufficient permissions
`404`	Not Found	Resource doesn’t exist or not accessible
`409`	Conflict	Resource already exists, duplicate entry
`422`	Unprocessable Entity	Valid syntax but semantic errors
`429`	Too Many Requests	Rate limit exceeded

Server Error Codes

Code	Name	Description
`500`	Internal Server Error	Unexpected server error
`502`	Bad Gateway	Upstream service unavailable
`503`	Service Unavailable	Server temporarily unavailable
`504`	Gateway Timeout	Upstream service timeout

API Error Response Format

All API errors follow this standardized flat format:

{
  "status": 400,
  "code": "INVALID_REQUEST",
  "message": "Event ID must be a valid UUID",
  "details": "optional additional context"
}

Field meanings:

status: HTTP status code (always matches response header)
code: Machine-readable error code for client-side branching
message: Human-readable message safe for UI display and developer debugging
details: Additional context (omitted if not needed), never raw error details

Authentication Errors

invalid_token

HTTP Status: 401Message: “Invalid or expired authentication token”Causes:

Token has expired (default: 1 hour)
Token was revoked
Token is malformed

Solutions:

Refresh the token using Clerk SDK
Sign out and sign back in
Check token format is Bearer <token>

# Verify token is being sent
curl -v -H "Authorization: Bearer $TOKEN" \
  http://localhost:4000/api/v1/users/me

missing_token

HTTP Status: 401Message: “Authentication token required”Causes:

Authorization header not included
Header format incorrect

Solutions:

Add Authorization: Bearer <token> header
Ensure token is not empty
Check for typos in header name

// Correct format
headers: {
  'Authorization': `Bearer ${token}`
}

token_expired

HTTP Status: 401Message: “Authentication token has expired”Causes:

JWT token exceeded its lifetime (1 hour default)

Solutions:

Call getToken() from Clerk to get fresh token
Clerk SDK handles refresh automatically in most cases
Check if user session is still valid

// React Native
const token = await getToken();

invalid_signature

HTTP Status: 401Message: “Token signature verification failed”Causes:

Token was modified
Wrong Clerk instance (test vs production)
Clerk secret key mismatch

Solutions:

Verify CLERK_SECRET_KEY matches Clerk Dashboard
Ensure using correct environment (test/prod)
Check token hasn’t been tampered with

Authorization Errors

forbidden

HTTP Status: 403Message: “You don’t have permission to perform this action”Causes:

User lacks required role (Owner/Admin)
Resource belongs to different organization
Feature requires higher subscription tier

Solutions:

Check user’s role in the organization
Verify organization membership
Check subscription tier for feature access

# Check user's organizations
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:4000/api/v1/users/me/organizations

not_member

HTTP Status: 403Message: “User is not a member of this organization”Causes:

User trying to access organization they don’t belong to
User was removed from organization

Solutions:

Verify user is member of the organization
Check if membership was revoked
Request invitation to organization

PLAN_UPGRADE_REQUIRED

HTTP Status: 403Message: ” is available on and above”Causes:

The organization’s plan is below the tier the feature needs in entitlements/registry.json, and that entitlement is enforced

The body also carries entitlement (the registry key), required_tier, and current_tier, so a client can name the plan to upgrade to:

{
  "status": 403,
  "code": "PLAN_UPGRADE_REQUIRED",
  "message": "Finances is available on Pro and above",
  "entitlement": "finances",
  "required_tier": "pro",
  "current_tier": "starter"
}

Solutions:

Upgrade the plan under Settings → Billing & payments → Billing
Check the org’s tier with GET /api/v1/organizations/{orgId}/entitlements

insufficient_role

HTTP Status: 403Message: “This action requires Owner or Admin role”Causes:

User has Member role, needs Admin or Owner
Specific action restricted to organization owner

Solutions:

Request role upgrade from organization owner
Use account with appropriate permissions

Validation Errors

validation_error

HTTP Status: 400Message: “Validation failed”Response includes details:

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": {
      "fields": {
        "email": "Invalid email format",
        "date": "Date must be in the future"
      }
    }
  }
}

Solutions:

Check the details.fields for specific errors
Validate input before sending
Ensure required fields are present

invalid_json

HTTP Status: 400Message: “Invalid JSON in request body”Causes:

Malformed JSON syntax
Missing Content-Type header
Empty request body when body expected

Solutions:

Validate JSON syntax
Add Content-Type: application/json header
Ensure body is not empty

# Validate JSON
echo '{"name": "test"}' | python -m json.tool

missing_field

HTTP Status: 400Message: “Required field missing: ”Causes:

Required field not included in request
Field name typo (camelCase vs snake_case)

Solutions:

Check API documentation for required fields
Verify field naming convention (API uses snake_case)

invalid_date

HTTP Status: 400Message: “Invalid date format”Expected format: ISO 8601 (2024-06-15T19:00:00Z)Solutions:

Use ISO 8601 format with timezone
Ensure date is valid (not Feb 30)

// Correct format
const date = new Date().toISOString();
// "2024-06-15T19:00:00.000Z"

Resource Errors

not_found

HTTP Status: 404Message: “Resource not found”Causes:

Resource doesn’t exist
Resource was deleted
Wrong ID format
No permission to view resource

Solutions:

Verify the resource ID is correct
Check if resource was deleted
Ensure user has access to the resource

# Check if event exists
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:4000/api/v1/events/{event_id}

already_exists

HTTP Status: 409Message: “Resource already exists”Causes:

Duplicate email address
Duplicate organization slug
Duplicate invitation for same user/event

Solutions:

Use unique values for unique fields
Check if resource already exists before creating
Update existing resource instead

resource_in_use

HTTP Status: 409Message: “Cannot delete resource that is in use”Causes:

Deleting position assigned to events
Deleting user with pending invitations

Solutions:

Remove references before deleting
Archive instead of delete

Webhook Errors

invalid_webhook_signature

HTTP Status: 401Message: “Webhook signature verification failed”Causes:

Wrong webhook secret
Request body modified in transit
Replay attack (timestamp too old)

Solutions:

Verify webhook secret matches service dashboard
Ensure raw body is used for signature verification
Check system clock is synchronized

webhook_processing_failed

HTTP Status: 500Message: “Failed to process webhook event”Causes:

Database error during processing
Required data missing in webhook payload

Solutions:

Check API logs for detailed error
Verify webhook payload format
Most webhooks auto-retry on failure

Rate Limiting

rate_limit_exceeded

HTTP Status: 429Message: “Too many requests”Response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1623456789

Solutions:

Implement exponential backoff
Cache responses where possible
Batch requests when possible
Wait until X-RateLimit-Reset timestamp

// Exponential backoff
const delay = Math.pow(2, retryCount) * 1000;
await new Promise(r => setTimeout(r, delay));

External Service Errors

stripe_error

HTTP Status: 502Message: “Payment service error”Causes:

Stripe API unavailable
Invalid Stripe API key
Card declined

Solutions:

Check Stripe status page
Verify Stripe API keys
Check card details for decline reason

twilio_error

HTTP Status: 502Message: “SMS service error”Causes:

Twilio API unavailable
Invalid phone number
Insufficient Twilio balance

Solutions:

Check Twilio status page
Verify phone number format (E.164)
Check Twilio account balance

clerk_error

HTTP Status: 502Message: “Authentication service error”Causes:

Clerk API unavailable
Invalid Clerk configuration

Solutions:

Check Clerk status page
Verify Clerk API keys
Retry after brief delay

Debugging Tips

Enable Verbose Logging

# cURL with verbose output
curl -v -H "Authorization: Bearer $TOKEN" \
  http://localhost:4000/api/v1/events

# Check response headers and body

Check API Logs

# Docker logs
docker compose logs -f api

# Filter for errors
docker compose logs api | grep -i error

Validate Request

# Test with minimal request
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Test Event", "date": "2024-12-01T19:00:00Z"}' \
  http://localhost:4000/api/v1/events

Getting Help

If you encounter an error not listed here:

Check the API logs for detailed error messages
Search the Troubleshooting guide
Check GitHub Issues for known issues
Ask in Slack #soundcheck-dev with:
- Error code and message
- Request details (endpoint, method, body)
- Steps to reproduce

Overview

Backend

Backend integrations

API reference

Frontend

Mobile

Infrastructure

CI/CD

Development

Guides

Reference

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

API Error Response Format

Authentication Errors

Authorization Errors

Validation Errors

Resource Errors

Webhook Errors

Rate Limiting

External Service Errors

Debugging Tips

Enable Verbose Logging

Check API Logs

Validate Request

Getting Help

​HTTP Status Codes

​Success Codes

​Client Error Codes

​Server Error Codes

​API Error Response Format

​Authentication Errors

​Authorization Errors

​Validation Errors

​Resource Errors

​Webhook Errors

​Rate Limiting

​External Service Errors

​Debugging Tips

​Enable Verbose Logging

​Check API Logs

​Validate Request

​Getting Help

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

API Error Response Format

Authentication Errors

Authorization Errors

Validation Errors

Resource Errors

Webhook Errors

Rate Limiting

External Service Errors

Debugging Tips

Enable Verbose Logging

Check API Logs

Validate Request

Getting Help