Handle responses

availability

Deployment: Invicti Platform on-demand, Invicti Platform on-premises

Part of API fundamentals series

This is part 5 of 5 in the API fundamentals series.
Previous: Make your first call

Understanding API response patterns and proper error handling is crucial for building reliable integrations with the Invicti Platform. This document explains response formats, status codes, and best practices for handling both successful responses and error conditions.

Response structure

All Invicti Platform API responses follow consistent patterns that help you handle data reliably.

Successful responses

Single resource:

{
  "id": "12345678-1234-1234-1234-123456789abc",
  "name": "Production Website",
  "url": "https://example.com",
  "status": "Active",
  "createdAt": "2024-03-01T10:00:00Z",
  "lastScanAt": "2024-03-23T14:30:00Z"
}

Collection of resources:

{
  "items": [
    {
      "id": "target-1",
      "name": "Target A",
      "url": "https://target-a.com"
    },
    {
      "id": "target-2",
      "name": "Target B",
      "url": "https://target-b.com"
    }
  ],
  "totalCount": 2,
  "page": 1,
  "pageSize": 50
}

Operation results:

{
  "success": true,
  "message": "Scan started successfully",
  "scanId": "scan-12345",
  "estimatedCompletionTime": "2024-03-23T16:45:00Z"
}

Response headers

Important headers included in responses:

Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1679580000

HTTP status codes

The API uses standard HTTP status codes to indicate request outcomes:

Code	Meaning	Notes
200 OK	Request successful	Response contains data
201 Created	Resource created successfully
204 No Content	Request successful	No response body - common for DELETE operations
400 Bad Request	Invalid request data	Response body contains validation details
401 Unauthorized	Authentication required or failed
403 Forbidden	Authenticated but insufficient permissions
404 Not Found	Resource doesn't exist
429 Too Many Requests	Rate limit exceeded	Response includes retryAfter value
500 Internal Server Error	Server-side issue	Response includes requestId for support
503 Service Unavailable	Service temporarily unavailable	Response includes retryAfter value

Validation and field errors

When requests contain invalid data, the API provides detailed validation information:

{
  "error": "ValidationError",
  "message": "Request validation failed",
  "details": [
    {
      "field": "url",
      "code": "REQUIRED",
      "message": "URL is required"
    },
    {
      "field": "name",
      "code": "TOO_LONG",
      "message": "Name must be 100 characters or less",
      "maxLength": 100,
      "providedLength": 150
    }
  ]
}

Debugging API issues

These techniques help you identify the cause of unexpected API behaviour.

Log requests and responses (Python example)

import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger(__name__)

def debug_api_call(method, url, headers, data=None):
    """Make API call with detailed logging for debugging."""
    logger.debug(f"REQUEST: {method} {url}")
    logger.debug(f"HEADERS: {headers}")
    if data:
        logger.debug(f"BODY: {json.dumps(data, indent=2)}")

    response = requests.request(method, url, headers=headers, json=data)

    logger.debug(f"RESPONSE: {response.status_code}")
    try:
        logger.debug(f"RESPONSE BODY: {json.dumps(response.json(), indent=2)}")
    except Exception:
        logger.debug(f"RESPONSE BODY: {response.text}")

    return response

Common debugging scenarios

Authentication issues (curl):

# Test authentication separately
curl -v -H "X-Auth: YOUR_KEY" \
  https://platform.invicti.com/api/identity/v1/me

Network connectivity (terminal):

# Test basic connectivity
ping platform.invicti.com

# Test HTTPS connectivity
curl -I https://platform.invicti.com

Best practices

1. Always verify HTTP status codes before processing response data
2. Log requests and responses for debugging
3. Handle validation errors gracefully with user-friendly messages

---

Next steps

You've completed the API fundamentals series. You now have a solid foundation to:

• Build complete workflows with multiple API calls
• Explore scanning workflows with the API scanning workflows series
• Integrate with CI/CD pipelines for continuous security testing
• Create custom tools using the Invicti Platform API

Complete fundamentals series

• Overview
• Part 1: When to use the API
• Part 2: Get your API key
• Part 3: Authenticate
• Part 4: Make your first call
• Part 5: Handle responses ← You are here

---

Need help?

Invicti Support team is ready to provide you with technical help. Go to Help Center