Error Codes Reference

All API error codes with explanations and resolutions.

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'priority' field must be one of: low, normal, high, critical",
    "field": "priority"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-14T10:30:00Z"
  }
}

Error Codes

UNAUTHORIZED (401)

Message: Missing or invalid API key

Causes:

  • No Authorization header
  • Invalid key format
  • Key has been revoked
  • Key has expired

Resolution:

  1. Verify you're sending the Authorization header
  2. Check the key format: Bearer sk_live_xxx or Bearer pk_live_xxx
  3. Confirm the key hasn't been revoked in Settings
  4. Create a new key if needed

FORBIDDEN (403)

Message: API key lacks required permissions

Causes:

  • Using publishable key for write operations
  • Accessing a different team's resources
  • Key permissions restricted

Resolution:

  • Use a secret key (sk_live_*) for create/update/delete
  • Verify you're accessing the correct team ID
  • Check key permissions in Settings

NOT_FOUND (404)

Message: Resource doesn't exist

Causes:

  • Invalid resource ID
  • Resource was deleted
  • Typo in the ID

Resolution:

  • Verify the resource ID is correct
  • List resources to find valid IDs
  • Check if the resource was recently deleted

VALIDATION_ERROR (400)

Message: Invalid request body/params

Causes:

  • Missing required fields
  • Invalid field values
  • Wrong data types

Resolution:

  • Check the error field property for which field failed
  • Review API docs for required fields and valid values
  • Ensure JSON is properly formatted

Example errors:

{ "code": "VALIDATION_ERROR", "message": "title is required", "field": "title" }
{ "code": "VALIDATION_ERROR", "message": "priority must be one of: low, normal, high, critical", "field": "priority" }
{ "code": "VALIDATION_ERROR", "message": "email is not a valid email address", "field": "email" }

RATE_LIMITED (429)

Message: Too many requests

Causes:

  • Exceeded rate limit for key type
  • Burst of requests in short time

Resolution:

  • Check X-RateLimit-Remaining header
  • Implement exponential backoff
  • Use caching where appropriate
  • Upgrade to higher limits if needed

Response includes:

{
  "code": "RATE_LIMITED",
  "message": "Rate limit exceeded. Try again in 42 seconds.",
  "retryAfter": 42
}

CONFLICT (409)

Message: Resource already exists or state conflict

Causes:

  • Duplicate email for customer
  • Duplicate slug for article
  • Invalid state transition

Resolution:

  • Use a unique value for the conflicting field
  • Check existing resources for duplicates
  • Verify the state change is valid

SERVER_ERROR (500)

Message: Internal server error

Causes:

  • Unexpected server issue
  • Temporary service disruption

Resolution:

  • Retry the request after a moment
  • If persistent, contact support with requestId
  • Check status page for outages

HTTP Status Codes Summary

Status Code Description
200 OK Success
201 Created Resource created
204 No Content Success (no body)
400 Bad Request VALIDATION_ERROR
401 Unauthorized UNAUTHORIZED
403 Forbidden FORBIDDEN
404 Not Found NOT_FOUND
409 Conflict CONFLICT
429 Too Many Requests RATE_LIMITED
500 Server Error SERVER_ERROR

Debugging Tips

  1. Use the requestId - Include it when contacting support
  2. Check field errors - The field property tells you exactly what failed
  3. Validate locally - Check JSON format before sending
  4. Log responses - Keep error responses for debugging

Related