Back to Documentation

Error Handling

Understand error responses and implement robust error handling.

Error Response Format

All API errors follow a consistent JSON format:

{
  "code": 400,
  "message": "Invalid request: missing required field 'input'",
  "error_type": "validation_error",
  "details": {
    "field": "input",
    "reason": "required"
  },
  "request_id": "req_abc123xyz"
}

HTTP Status Codes

Success (2xx)

200OK— Request succeeded
201Created— Resource created successfully

Client Errors (4xx)

400Bad Request— Invalid request format or parameters
401Unauthorized— Missing or invalid API token
403Forbidden— Token valid but lacks permission
404Not Found— Resource does not exist
409Conflict— Resource already exists
422Unprocessable— Validation failed
429Too Many Requests— Rate limit exceeded

Server Errors (5xx)

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

Error Types

Error TypeDescriptionAction
authentication_errorInvalid or missing API tokenCheck your token is correct and not expired
authorization_errorToken lacks required permissionsEnsure you have purchased the skill
validation_errorRequest data failed validationCheck required fields and data types
not_found_errorRequested resource not foundVerify the skill slug or ID exists
rate_limit_errorToo many requestsImplement exponential backoff
execution_errorSkill execution failedCheck skill input format and try again
internal_errorServer-side errorRetry with exponential backoff

Common Errors & Solutions

Invalid API Token
401
{
  "code": 401,
  "message": "Invalid or expired API token",
  "error_type": "authentication_error"
}
Solution: Verify your token starts with 'sk-bring-' and hasn't been deleted. Generate a new token if needed.
Skill Not Purchased
403
{
  "code": 403,
  "message": "You have not purchased this skill",
  "error_type": "authorization_error",
  "details": {
    "skill_slug": "premium-analyzer"
  }
}
Solution: Purchase the skill from the marketplace before executing it.
Invalid Input
422
{
  "code": 422,
  "message": "Validation failed",
  "error_type": "validation_error",
  "details": {
    "errors": [
      {"field": "input.text", "message": "Required field missing"}
    ]
  }
}
Solution: Check the skill's input schema and provide all required fields.
Rate Limited
429
{
  "code": 429,
  "message": "Rate limit exceeded",
  "error_type": "rate_limit_error",
  "details": {
    "limit": 100,
    "window": "1m",
    "retry_after": 45
  }
}
Solution: Wait for the retry_after period, then retry. Implement exponential backoff for production.

Best Practices

Always check the status code

Don't assume success. Check HTTP status codes and handle errors appropriately.

const response = await fetch(url, options);

if (!response.ok) {
  const error = await response.json();
  throw new Error(`API Error: ${error.message}`);
}

const data = await response.json();

Implement retry logic

For transient errors (5xx, 429), implement exponential backoff.

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.ok) return response.json();
    
    if (response.status === 429 || response.status >= 500) {
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await new Promise(r => setTimeout(r, delay));
      continue;
    }
    
    throw new Error(`API Error: ${response.status}`);
  }
  throw new Error('Max retries exceeded');
}

Log request IDs

Always log the request_id from error responses for debugging.

try {
  const result = await executeSkill(input);
} catch {
  console.error('Skill execution failed', {
    message: error.message,
    request_id: error.request_id, // Include in support tickets
    timestamp: new Date().toISOString()
  });
}

Rate Limits

Free Tier

100

requests / minute

Pro Tier

1,000

requests / minute

Enterprise

Custom

Contact sales

Rate Limit Headers

Check X-RateLimit-Remaining and X-RateLimit-Reset headers to monitor your usage.

Agent IntegrationAPI Reference