Error Codes

Reference for all API error codes and how to handle them.

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message",
    "details": {
      "field": "Additional context"
    },
    "requestId": "req_abc123"
  }
}

Authentication Errors

Code	HTTP	Description
UNAUTHORIZED	401	Missing or invalid token
TOKEN_EXPIRED	401	Token has expired
INVALID_API_KEY	401	API key not recognized
INSUFFICIENT_SCOPE	403	Token lacks required scope

Resource Errors

Code	HTTP	Description
NOT_FOUND	404	Resource doesn't exist
ALREADY_EXISTS	409	Resource already exists
DELETED	410	Resource was deleted

Validation Errors

Code	HTTP	Description
INVALID_REQUEST	400	Malformed request body
MISSING_FIELD	400	Required field missing
INVALID_FORMAT	400	Field format invalid
VALUE_TOO_LONG	400	Field exceeds max length

Rate Limiting

Code	HTTP	Description
RATE_LIMIT_EXCEEDED	429	Too many requests
QUOTA_EXCEEDED	429	Plan quota reached

Server Errors

Code	HTTP	Description
INTERNAL_ERROR	500	Unexpected server error
SERVICE_UNAVAILABLE	503	Temporary unavailable
TIMEOUT	504	Request timed out

Handling Errors

try {
  const response = await api.createProject(data);
} catch (error) {
  switch (error.code) {
    case 'ALREADY_EXISTS':
      showToast('Project name already taken');
      break;
    case 'RATE_LIMIT_EXCEEDED':
      await delay(error.details.retryAfter);
      retry();
      break;
    default:
      reportError(error);
  }
}

Getting Help

Include requestId when contacting support - it helps us debug issues quickly.