Catalog API Documentation

Browse endpoints, parameters, and live request examples.

Sandbox Error Testing Guide

Test your error handling and resilience by simulating various failure conditions in the sandbox. The sandbox endpoints supports special headers that allow frontend developers to simulate various error conditions without needing to trigger actual errors. This is useful for testing error handling, retry logic, and user experience during failures.

Supported Test Headers

1. X-Simulate-Error

Triggers specific HTTP error responses with consistent error format.

Header Value	HTTP Status	Response
400	400 Bad Request	Standard bad request error
401	401 Unauthorized	Standard auth error (same as missing API key)
403	403 Forbidden	Access denied error
404	404 Not Found	Resource not found error
409	409 Conflict	Conflict error
422	422 Unprocessable	Validation error
429	429 Too Many Requests	Rate limit error (with headers)
500	500 Internal Error	Server error
502	502 Bad Gateway	Gateway error
503	503 Unavailable	Service unavailable
Any 4xx/5xx	Custom status	Generic error with that status

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
 -H "X-Simulate-Error: 503" \
 https://api.catalogapi.com/sandbox/api/v2/sockets

Example Response:

{
  "success": false,
  "timestamp": "2024-01-15T10:30:00Z",
  "message": "Service Unavailable - Simulated error for testing",
  "error_code": "SERVICE_UNAVAILABLE",
  "simulated": true
}

Note: Some network hardware in the stack may return a 503 without our specific error formatting above.

2. X-Simulate-Timeout

Simulates a slow response/timeout. Value is in milliseconds (max 60000ms).

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
 -H "X-Simulate-Timeout: 5000" \
 https://api.catalogapi.com/sandbox/api/v2/sockets

This will wait 5 seconds, then return:

{
  "success": false,
  "timestamp": "2024-01-15T10:30:05Z",
  "message": "Gateway Timeout - Simulated after 5000ms",
  "error_code": "GATEWAY_TIMEOUT",
  "simulated": true,
  "timeout_ms": 5000
}

Note: Some network hardware in the stack may return a 504 without our specific error formatting above.

3. X-Simulate-Rate-Limit

Simulates hitting the rate limit with proper headers.

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
 -H "X-Simulate-Rate-Limit: true" \
 https://api.catalogapi.com/sandbox/api/v2/sockets

Response Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705321800
Retry-After: 3600

Response Body:

{
  "success": false,
  "timestamp": "2024-01-15T10:30:00Z",
  "message": "Too many requests. Please retry after some time.",
  "error_code": "RATE_LIMIT_EXCEEDED",
  "simulated": true,
  "retry_after_seconds": 3600
}

4. X-Simulate-Partial-Response

Returns malformed/incomplete JSON to test parsing error handling.

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
 -H "X-Simulate-Partial-Response: true" \
 https://api.catalogapi.com/sandbox/api/v2/sockets

Response (Intentionally malformed):

{"success": true, "data": [{"id": 1, "name": "Test"

5. X-Simulate-Empty-Response

Returns completely empty response body with 200 status.

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
 -H "X-Simulate-Empty-Response: true" \
 https://api.catalogapi.com/sandbox/api/v2/sockets

Response (Empty body):

6. X-Simulate-Network-Error

Simulates an abrupt connection close (network failure).

Example Request:

curl -H "Authorization: Bearer YOUR_TOKEN" \
 -H "X-Simulate-Network-Error: true" \
 https://api.catalogapi.com/sandbox/api/v2/sockets

Result: Connection closed without proper response