API Errors

Troubleshoot common API issues.

Authentication Errors

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Causes:

Missing Authorization header
Invalid API key
Expired API key
Revoked API key

Solutions:

Check header format:

# Correct
-H "Authorization: Bearer YOUR_API_KEY"

# Wrong - missing Bearer
-H "Authorization: YOUR_API_KEY"

Verify key is valid:
- Check key in Settings → API Keys
- Ensure key isn't expired
- Create new key if needed

Test key:

curl -X GET "https://api.blocksecops.com/api/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

403 Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions"
  }
}

Causes:

API key lacks required permission
Resource belongs to different organization
Action not allowed for your plan

Solutions:

Check key permissions:
- Go to Settings → API Keys
- View key's scopes
- Create new key with needed permissions

Verify organization:

# Specify organization if needed
-H "X-Organization-ID: org_xyz"

Request Errors

400 Bad Request

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required field: contract_id"
  }
}

Causes:

Missing required parameters
Invalid parameter format
Malformed JSON

Solutions:

Check required fields:

# Correct
curl -X POST ".../scans" \
  -d '{"contract_id": "abc123", "preset": "standard"}'

# Wrong - missing contract_id
curl -X POST ".../scans" \
  -d '{"preset": "standard"}'

Validate JSON:
```
echo '{"contract_id": "abc"}' | jq .
```

404 Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Scan not found"
  }
}

Causes:

Invalid resource ID
Resource was deleted
Resource in different organization

Solutions:

Verify resource exists:

# List resources to find correct ID
curl "https://api.blocksecops.com/api/v1/scans" \
  -H "Authorization: Bearer YOUR_API_KEY"

Check organization context:
- Resource may be in different org
- Use X-Organization-ID header

Rate Limiting

429 Too Many Requests

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

Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705323600
Retry-After: 45

Solutions:

Wait and retry:

# Wait for Retry-After seconds
sleep $RETRY_AFTER

Implement backoff:

import time

def api_call_with_retry(url, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            wait = int(response.headers.get('Retry-After', 60))
            time.sleep(wait * (2 ** attempt))
            continue
        return response

Reduce request frequency:
- Cache results
- Use webhooks instead of polling
- Batch operations

Upload Errors

"File Too Large"

{
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File exceeds 50MB limit"
  }
}

Solutions:

Reduce file size
Exclude unnecessary files
Use Enterprise for larger limits

"Invalid File Type"

{
  "error": {
    "code": "INVALID_FILE_TYPE",
    "message": "Unsupported file format"
  }
}

Supported:

.sol, .vy, .rs
.zip, .tar.gz

Scan Errors

"Scan Already Running"

{
  "error": {
    "code": "SCAN_IN_PROGRESS",
    "message": "A scan is already running for this contract"
  }
}

Solutions:

Wait for current scan to complete
Cancel existing scan if needed
Check scan status first

"Concurrent Limit"

{
  "error": {
    "code": "CONCURRENT_LIMIT",
    "message": "Maximum concurrent scans reached"
  }
}

Solutions:

Wait for scans to complete
Upgrade plan for higher limits

Server Errors

500 Internal Server Error

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}

Solutions:

Retry the request:
- Transient errors may resolve
- Use exponential backoff
Check status page:
- Look for outages
- Check maintenance windows
Contact support:
- If persistent
- Include request ID from headers

503 Service Unavailable

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable"
  }
}

Causes:

Maintenance in progress
High load
Temporary outage

Solutions:

Wait and retry
Check status page
Use exponential backoff

Debugging Tips

Include Request ID

Response headers include request ID:

X-Request-ID: req_abc123xyz

Include this when contacting support.

Verbose curl

curl -v -X POST "https://api.blocksecops.com/api/v1/scans" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contract_id": "abc123"}'

Check Response Headers

curl -I "https://api.blocksecops.com/api/v1/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

Common Mistakes

Wrong Content-Type

# For JSON requests
-H "Content-Type: application/json"

# For file uploads
-F "[email protected]"  # Don't set Content-Type manually

Escaping Issues

# Careful with shell escaping
# Use single quotes for JSON
-d '{"key": "value"}'

# Or escape double quotes
-d "{\"key\": \"value\"}"

URL Encoding

# Encode special characters
curl "https://api.blocksecops.com/api/v1/search?q=test%20value"

Still Having Issues?

Provide to support:

Full request (redact API key)
Full response including headers
Request ID
Timestamp
Steps to reproduce

See Contact Support.