Skip to main content

​
Error Response Format

All API errors follow a consistent JSON structure: 
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {
      "field": "specific_field",
      "issue": "Detailed issue description"
    }
  }
}

​
HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of requests:
​
200
OK
Request succeeded
​
201
Created
Resource created successfully
​
400
Bad Request
Invalid request parameters or payload
​
401
Unauthorized
Missing or invalid API key
​
403
Forbidden
Insufficient permissions for the requested action
​
404
Not Found
Requested resource does not exist
​
409
Conflict
Resource already exists (e.g., duplicate link code)
​
422
Unprocessable Entity
Request payload validation failed
​
429
Too Many Requests
Rate limit exceeded
​
500
Internal Server Error
Unexpected server error

​
Common Error Codes

​
Authentication Errors

​
INVALID_API_KEY
401
The provided API key is missing, malformed, or invalid
​
API_KEY_EXPIRED
401
The API key has expired and needs to be regenerated
​
INSUFFICIENT_PERMISSIONS
403
The API key does not have permission to perform this action

​
Validation Errors

​
VALIDATION_ERROR
422
Request payload failed validation. Check the details field for specific issues.
​
INVALID_PARAMETERS
400
Query parameters are invalid or out of acceptable range
​
MISSING_REQUIRED_FIELD
422
A required field is missing from the request payload

​
Resource Errors

​
LINK_NOT_FOUND
404
The requested link does not exist or you don’t have access to it
​
CODE_ALREADY_EXISTS
409
A link with the specified code already exists
​
LINK_EXPIRED
410
The link has expired and is no longer accessible

​
Rate Limiting

​
RATE_LIMIT_EXCEEDED
429
You have exceeded your API rate limit. Wait before making more requests.

​
Subscription Errors

​
SUBSCRIPTION_REQUIRED
402
An active subscription is required to perform this action
​
SUBSCRIPTION_LIMIT_EXCEEDED
402
You have reached your subscription’s usage limits
​
PAYMENT_REQUIRED
402
Payment is required to continue using the service

​
Error Handling Best Practices

​
1. Check the success Field

Always check the success field in the response to determine if the request was successful: 
const response = await fetch('https://api.bit2connect.com/api/links', {
  headers: { 'Authorization': 'Bearer b2co_your_api_key' }
});

const data = await response.json();

if (!data.success) {
  console.error('API Error:', data.error.code, data.error.message);
  // Handle error appropriately
}

​
2. Handle Specific Error Codes

Different error codes may require different handling strategies: 
switch (data.error.code) {
  case 'INVALID_API_KEY':
    // Redirect to API key setup
    break;
  case 'RATE_LIMIT_EXCEEDED':
    // Implement exponential backoff
    break;
  case 'LINK_NOT_FOUND':
    // Show user-friendly "not found" message
    break;
  default:
    // Generic error handling
}

​
3. Implement Retry Logic

For transient errors (5xx status codes, rate limits), implement retry logic with exponential backoff: 
async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      const data = await response.json();
      
      if (data.success) {
        return data;
      }
      
      // Don't retry client errors (4xx)
      if (response.status >= 400 && response.status < 500) {
        throw new Error(data.error.message);
      }
      
      // Retry server errors with exponential backoff
      if (i < maxRetries - 1) {
        await new Promise(resolve => 
          setTimeout(resolve, Math.pow(2, i) * 1000)
        );
      }
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

​
4. Log Errors for Debugging

Always log errors with sufficient context for debugging: 
console.error('Bit2Connect API Error:', {
  endpoint: url,
  method: options.method,
  statusCode: response.status,
  errorCode: data.error.code,
  errorMessage: data.error.message,
  requestId: response.headers.get('x-request-id')
});

​
Rate Limiting Details

When you exceed your rate limit, the API returns a 429 status code with additional headers:
  • X-RateLimit-Limit: Your rate limit per hour
  • X-RateLimit-Remaining: Remaining requests in current window
  • X-RateLimit-Reset: Unix timestamp when the rate limit resets
if (response.status === 429) {
  const resetTime = response.headers.get('X-RateLimit-Reset');
  const waitTime = (resetTime * 1000) - Date.now();
  console.log(`Rate limited. Retry after ${waitTime}ms`);
}