Error Reference

Complete reference of error codes and responses returned by the Singlebase API.

Response Format

All errors return this structure:

{
  "type": "NOT_FOUND",
  "status": 404,
  "message": "USER_NOT_FOUND",
  "details": {},
  "trace_id": "abc-123"
}

Field	Type	Description
type	string	Error category (matches HTTP status)
status	integer	HTTP status code
message	string	Error code or description
details	object	Additional context (optional)
trace_id	string	Error tracking ID (optional)

---

Error Codes

400 - Bad Request

Invalid request format or parameters. This occurs when the request is malformed, contains invalid data, or is missing required fields.

Code	Description
BAD_REQUEST	Generic bad request
VALIDATION_ERROR	Validation failed
MISSING_REQUIRED_FIELD	Required field missing
INVALID_LENGTH	String/array length invalid
INVALID_JSON	Malformed JSON
INVALID_HEADER	Invalid HTTP header
INVALID_FILE_FORMAT	Unsupported file format
BATCH_LIMIT_EXCEEDED	Too many items in batch

401 - Unauthorized

Authentication is required or has failed. This occurs when credentials are missing, invalid, or expired.

Code	Description
AUTHENTICATION_ERROR	Authentication failed
INVALID_CREDENTIALS	Wrong username/password
INVALID_TOKEN	Malformed token

403 - Forbidden

Access to the resource is denied. This occurs when authenticated but lacking proper permissions or the resource is restricted.

Code	Description
FORBIDDEN_ERROR	Access forbidden
FORBIDDEN_RESOURCE	Resource access denied
RESOURCE_LOCKED	Resource locked

404 - Not Found

The requested resource does not exist. This occurs when the resource has been deleted, archived, or never existed.

Code	Description
NOT_FOUND	Resource not found
DELETED	Resource deleted
ARCHIVED	Resource archived
EMPTY	Collection empty
ACTION_NOT_FOUND	Action not found

405 - Method Not Allowed

HTTP method not supported for this endpoint. This occurs when using the wrong HTTP verb (GET, POST, etc.) for a specific operation.

Code	Description
METHOD_NOT_ALLOWED	HTTP method not supported

406 - Not Acceptable

Requested media type cannot be provided. This occurs when the server cannot produce a response matching the Accept header.

Code	Description
UNSUPPORTED_MEDIA_TYPE	Media type not supported

408 - Request Timeout

Request took too long to complete. This occurs when the server terminates a connection that's taking too long to process.

Code	Description
REQUEST_TIMEOUT	Request took too long

409 - Conflict

Request conflicts with current resource state. This occurs when trying to create a duplicate resource or violating data constraints.

Code	Description
CONFLICT	Resource conflict

413 - Payload Too Large

Request body exceeds size limit. This occurs when uploading files or sending data that's too large.

Code	Description
REQUEST_ENTITY_TOO_LARGE	Request body too large

415 - Unsupported Media Type

Content-Type header not supported. This occurs when sending data in an unsupported format.

Code	Description
UNSUPPORTED_CONTENT_TYPE	Content-Type not supported

429 - Too Many Requests

Rate limit exceeded. This occurs when making too many requests in a given time period or exceeding usage quotas.

Code	Description
TOO_MANY_REQUESTS	Rate limit exceeded
RATE_LIMIT_EXCEEDED	Request rate too high
QUOTA_EXCEEDED	Usage quota exceeded

500 - Internal Server Error

Server encountered an unexpected error. This occurs when something goes wrong on the server side.

Code	Description
SERVER_ERROR	Generic server error

503 - Service Unavailable

Service is temporarily unavailable. This occurs during maintenance or when the service is overloaded.

Code	Description
SERVICE_UNAVAILABLE	Service temporarily unavailable
MAINTENANCE_MODE	Under maintenance

---

Examples

Validation Error

{
  "type": "VALIDATION_ERROR",
  "status": 400,
  "message": "MISSING_REQUIRED_FIELD",
  "details": {
    "field": "email",
    "requirement": "required"
  }
}

Authentication Error

{
  "type": "EXPIRED_TOKEN",
  "status": 401,
  "message": "TOKEN_EXPIRED",
  "details": {
    "expired_at": "2024-01-15T10:30:00Z"
  }
}

Not Found

{
  "type": "NOT_FOUND",
  "status": 404,
  "message": "USER_NOT_FOUND",
  "details": {
    "user_id": "12345"
  }
}

Rate Limit

{
  "type": "RATE_LIMIT_EXCEEDED",
  "status": 429,
  "message": "TOO_MANY_REQUESTS",
  "details": {
    "limit": 100,
    "window": "1h",
    "retry_after": 3600
  }
}

Error Handling Best Practices

Retry Logic

async function apiRequestWithRetry(requestData, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch('https://cloud.singlebaseapis.com/api/$ENDPOINT_KEY', {
        method: 'POST',
        headers: {
          'X-API-KEY': 'your-api-key',
          'Authorization': 'Bearer your-token',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(requestData)
      });

      if (!response.ok) {
        const error = await response.json();
        
        // Don't retry for client errors
        if (response.status >= 400 && response.status < 500) {
          throw new Error(error.message);
        }
        
        // Retry for server errors
        if (attempt === maxRetries) {
          throw new Error(`Max retries reached: ${error.message}`);
        }
        
        // Exponential backoff
        await new Promise(resolve => 
          setTimeout(resolve, Math.pow(2, attempt) * 1000)
        );
        continue;
      }

      return await response.json();
    } catch (error) {
      if (attempt === maxRetries) throw error;
    }
  }
}

Error Response Handling

function handleApiError(error) {
  switch (error.type) {
    case 'AUTHENTICATION_FAILED':
      // Redirect to login
      redirectToLogin();
      break;
    case 'TOKEN_EXPIRED':
      // Attempt token refresh
      refreshAuthToken();
      break;
    case 'VALIDATION_ERROR':
      // Show validation errors to user
      showValidationErrors(error.details);
      break;
    case 'RATE_LIMIT_EXCEEDED':
      // Implement exponential backoff
      scheduleRetry(error.details.retry_after);
      break;
    default:
      // Generic error handling
      showErrorMessage(error.message);
  }
}