Error Handling and Troubleshooting

Common Error Types

Authentication Errors

Invalid Client Credentials

• HTTP Status: 401 Unauthorized
• Cause: Incorrect client ID or secret
• Solution: Verify your credentials and environment

Missing OAuth Token

• HTTP Status: 401 Unauthorized
• Cause: User hasn't completed OAuth flow
• Solution: Ensure user completes OAuth before making requests

Invalid Token

• HTTP Status: 401 Unauthorized
• Cause: OAuth token is invalid or has been revoked
• Solution: Restart OAuth flow to obtain a new token

Permission Errors

Missing Required Permissions

• HTTP Status: 403 Forbidden
• Cause: User didn't grant required permissions
• Solution: Ensure OAuth scope includes required permissions

Insufficient Permissions

• HTTP Status: 403 Forbidden
• Cause: User lacks permission for specific operation
• Solution: Check user's permission level

Payment Errors

Insufficient Balance

• HTTP Status: 402 Payment Required
• Cause: User doesn't have enough balance
• Solution: Use preview charge to check balance first

Daily Spending Limit Exceeded

• HTTP Status: 402 Payment Required
• Cause: User reached daily spending limit
• Solution: Inform user of limit and suggest alternatives

Validation Errors

Invalid Request Data

• HTTP Status: 400 Bad Request
• Cause: Request body doesn't match schema
• Solution: Validate request data before sending

Missing Required Fields

• HTTP Status: 400 Bad Request
• Cause: Required fields are missing
• Solution: Include all required fields in request

Error Response Format

{
  "status": "error",
  "message": "Error description",
  "code": "ERROR_CODE",
  "details": {
    "field": "Additional error details"
  }
}

Debugging Tips

• Enable Debug Logging: Log all API requests and responses
• Check Request Headers: Ensure all required headers are present
• Validate Request Data: Use schema validation before sending requests
• Test in Sandbox: Always test in sandbox environment first
• Monitor Webhooks: Ensure webhook endpoints are accessible