Riskwolf API Error Cases and Codes

Overview

This document outlines the various error scenarios, expected response codes, and handling recommendations for the Riskwolf External Quotes API.

HTTP Status Codes

Status Code	Description	Usage
200	OK	Successful quote generation
400	Bad Request	Invalid input parameters
401	Unauthorized	Authentication issues
403	Forbidden	Authorization issues
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side issues

Error Categories

1. Authentication & Authorization

Scenario	Expected Code	Description
Missing token	401	No Bearer token provided
Invalid token	401	Malformed or corrupt token
Expired token	401	Token has expired
Invalid permissions	403	Token lacks required roles
Missing tenant ID	401	x-tenant-id header not provided
Invalid tenant ID	403	Tenant ID not authorized

2. Date Validation

Scenario	Expected Code	Description
End before start	400	End date precedes start date
Invalid format	400	Date not in ISO 8601 format
Future date limit	400	Date beyond allowed future range
Past date	400	Historical dates not allowed
Same dates	400	Start and end dates identical
Long duration	400	Period exceeds maximum duration

3. Sum Insured Validation

Scenario	Expected Code	Description
Negative amount	400	Amount less than zero
Zero amount	400	Amount equals zero
Excessive amount	400	Amount exceeds maximum limit
Invalid currency	400	Unsupported currency code
Missing amount	400	Required amount field missing
Decimal precision	400	Too many decimal places

4. Monitoring Target ID

Scenario	Expected Code	Description
Invalid format	400	ID format doesn't match pattern
Non-existent	404	ID not found in system
Wrong region	400	Region code mismatch
Invalid version	400	Version number invalid
Inactive target	403	Target no longer active

5. Request Format

Scenario	Expected Code	Description
Invalid JSON	400	Malformed JSON body
Missing fields	400	Required fields not provided
Unknown fields	400	Unexpected additional fields
Wrong content-type	415	Invalid content type header
Empty body	400	Request body is empty

6. Rate Limiting

Scenario	Expected Code	Description
Too many requests	429	Rate limit exceeded
Quota exceeded	429	Daily/monthly quota reached
Concurrent limit	429	Too many parallel requests

Error Response Format

{
    "error": {
        "code": "ERROR_CODE",
        "message": "Human readable error message",
        "details": {
            "field": "Field causing error",
            "reason": "Specific reason for error"
        },
        "requestId": "Unique request identifier",
        "timestamp": "2024-11-27T10:44:47.774+00:00"
    }
}

Best Practices for Error Handling

1. Retry Strategy
2. Retry 429 errors with exponential backoff
3. Don't retry 400-level errors

4. Implement circuit breaker for 500-level errors

5. Logging

6. Always log the requestId for tracking
7. Include timestamp and full error response

8. Log correlation IDs if provided

9. User Communication

10. Display user-friendly error messages
11. Include support contact for 500 errors

12. Show appropriate recovery actions

13. Security

14. Don't expose internal error details
15. Validate all input parameters
16. Handle sensitive data appropriately

Example Error Scenarios

Invalid Date Range

{
    "error": {
        "code": "INVALID_DATE_RANGE",
        "message": "End date must be after start date",
        "details": {
            "field": "riskPeriodTo",
            "reason": "2024-12-01 is before riskPeriodFrom 2024-12-31"
        },
        "requestId": "req_123abc",
        "timestamp": "2024-11-27T10:44:47.774+00:00"
    }
}

Rate Limit Exceeded

```json { "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Too many requests", "details": { "rateLimitReset": "2024-11-27T10:45:47.774+00:00", "currentUsage": "100/100" }, "requestId": "req_456def", "timestamp": "2024-11-27T10:44:47.774+00:00" } }