Troubleshooting

Common errors and solutions.

Authentication Errors

401 Unauthorized

Error:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key"
  }
}

Causes:

• Missing Authorization header
• Invalid API key
• Malformed Bearer token

Solutions:

1. Ensure header format is Authorization: Bearer YOUR_API_KEY
2. Verify API key is correct (check for extra spaces)
3. Generate a new API key if compromised

# Correct format
curl -H "Authorization: Bearer bso_live_xyz789abc..." ...

# Common mistakes
curl -H "Authorization: bso_live_xyz789abc..." ...        # Missing "Bearer"
curl -H "Authorization:Bearer bso_live_xyz789abc..." ...  # Missing space

403 Forbidden

Error:

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Insufficient permissions for this operation"
  }
}

Causes:

• API key lacks required permission scope
• Accessing another user's resource
• Enterprise feature on lower tier

Solutions:

1. Check required scope for the endpoint
2. Update API key permissions in dashboard
3. Create new key with correct permissions

# Check your key's permissions
curl -X GET "https://api.blocksecops.com/api/v1/api-keys" \
  -H "Authorization: Bearer YOUR_API_KEY"

Key Expired

Error:

{
  "error": {
    "code": "KEY_EXPIRED",
    "message": "API key has expired"
  }
}

Solution:

1. Create a new API key
2. Update applications with new key
3. Consider longer expiration next time

---

Pagination Errors

Invalid Cursor

Error:

{
  "error": {
    "code": "INVALID_CURSOR",
    "message": "The provided cursor is invalid or malformed"
  }
}

Causes:

• Cursor string was modified or truncated
• Using cursor from different endpoint
• Copy/paste error
• Cursor doesn't decode to valid JSON

Solutions:

1. Use cursor exactly as returned by API
2. Don't modify or encode cursor values
3. Start from first page if cursor is lost
4. Cursors are base64url encoded - don't add padding

Cursor Expired

Error:

{
  "error": {
    "code": "CURSOR_EXPIRED",
    "message": "Cursor has expired due to data changes"
  }
}

Causes:

• Significant data changes since cursor was created
• Very old cursor

Solution:
Start pagination from the beginning without a cursor.

Invalid Pagination Parameters

Error:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Cannot use first/after with last/before"
  }
}

Causes:

• Using both forward and backward pagination params
• first and last specified together

Solutions:

1. Use only first/after for forward pagination
2. Use only last/before for backward pagination
3. Don't mix forward and backward params

---

Rate Limiting

429 Too Many Requests

Error:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded"
  }
}

Solutions:

1. Check headers for reset time:

   X-RateLimit-Reset: 1704931200
   Retry-After: 300
   

2. Implement exponential backoff:

   import time
   
   wait_time = 2 ** attempt  # 1, 2, 4, 8, 16 seconds
   time.sleep(wait_time)
   

3. Reduce request frequency:

   • Batch operations
   • Cache responses
   • Use webhooks for events

4. Upgrade plan for higher limits

---

Scan Errors

Scan Failed

Error:

{
  "error": {
    "code": "SCAN_FAILED",
    "message": "Scan failed during execution"
  }
}

Causes:

• Invalid contract syntax
• Unsupported Solidity version
• Contract too large

Solutions:

1. Verify contract compiles locally
2. Check supported Solidity versions
3. Split large contracts into smaller files

Quota Exceeded

Error:

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly scan quota exceeded"
  }
}

Solutions:

1. Wait for quota reset (first of month)
2. Upgrade to higher plan
3. Check quota usage: GET /users/me/quota

---

Upload Errors

File Too Large

Error:

{
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File exceeds maximum size limit"
  }
}

Limits:

• Single file: 10 MB
• Zip archive: 50 MB

Solutions:

1. Remove unnecessary files
2. Split into multiple uploads
3. Contact support for enterprise limits

Invalid File Type

Error:

{
  "error": {
    "code": "INVALID_FILE_TYPE",
    "message": "File type not supported"
  }
}

Supported types:

• .sol - Solidity
• .vy - Vyper
• .rs - Rust (Solana)
• .move - Move
• .cairo - Cairo
• .zip - Archive containing above

---

Resource Errors

404 Not Found

Error:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found"
  }
}

Causes:

• Invalid resource ID
• Resource was deleted
• Accessing another user's resource

Solutions:

1. Verify resource ID is correct
2. Check if resource still exists
3. Ensure you have access to the resource

409 Conflict

Error:

{
  "error": {
    "code": "CONFLICT",
    "message": "Resource state conflict"
  }
}

Causes:

• Duplicate resource
• Concurrent modification
• Invalid state transition

Solutions:

1. Check if resource already exists
2. Retry with fresh data
3. Use optimistic locking if available

---

Getting Help

If you can't resolve an issue:

1. Check status page: status.blocksecops.com
2. Search documentation: docs.blocksecops.com
3. Community Discord: discord.gg/blocksecops
4. Email support: [email protected]

Include in support requests:

• Request ID (from response headers)
• Endpoint and method
• Error message
• Timestamp