waddling-errors-macros 0.7.3

Procedural macros for structured error codes with compile-time validation and taxonomy enforcement
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

//! API Integration Component
//!
//! External API integrations - third-party service calls, webhooks, rate limiting.
//!
//! This version uses the `component!` and `diag!` macros from waddling-errors-macros.

use waddling_errors_macros::{component, component_location, diag};

component! {
    Api {
        docs: "External API integrations. Manages third-party service calls, webhook handling, and API rate limiting.",
        examples: [
            "B.Api.RateLimit.EXCEEDED: Rate limit exceeded (100 req/min)",
            "E.Api.Connection.UNREACHABLE: Third-party API unreachable",
            "W.Api.Validation.INVALID: Response schema validation warning"
        ],
        tags: ["integration", "http", "webhooks"],
    },
}

component_location!(Api, role = developer);

// ============================================================================
// Error Code Definitions
// ============================================================================

diag! {
    <json, html>,


    B.Api.RateLimit.EXCEEDED: {
        message: "API rate limit exceeded",
        'CR 'Pub description: "The API rate limit has been exceeded. Too many requests were made in the configured time window.",
        'CR 'Pub hints: [
            "Implement backoff",
            "Check X-RateLimit-Reset",
            "Cache responses"
        ],
        'R role: "Public",
        'R tags: ["api", "rate-limiting"],
    },

    E.Api.Connection.UNREACHABLE: {
        message: "Third-party API unreachable",
        'CR 'Pub description: "The third-party API endpoint could not be reached. This indicates a network connectivity issue or the API service is down.",
        'CR 'Pub hints: [
            "Check network",
            "Verify endpoint URL",
            "Check service status"
        ],
        'CR 'Dev hints: [
            "Review firewall rules",
            "Check DNS resolution",
            "Verify SSL certificates"
        ],
        'R role: "Developer",
        'R tags: ["api", "network", "external"],
    },

    E.Api.Connection.UNAVAILABLE: {
        message: "Third-party API temporarily unavailable",
        'CR 'Pub description: "The third-party API is temporarily unavailable. The service is experiencing issues but is expected to recover.",
        'CR 'Pub hints: [
            "Retry after delay",
            "Enable circuit breaker",
            "Use fallback"
        ],
        'CR 'Dev hints: [
            "Implement exponential backoff",
            "Monitor service status page"
        ],
        'R role: "Developer",
        'R tags: ["api", "resilience"],
    },

    W.Api.Validation.INVALID: {
        message: "API response validation warning",
        'CR 'Pub description: "The API response failed schema validation. The response structure may have changed or contains unexpected data.",
        'CR 'Pub hints: [
            "Check API version",
            "Review schema changes",
            "Update client"
        ],
        'CR 'Dev hints: [
            "Log response payload for debugging",
            "Update JSON schema definitions"
        ],
        'R role: "Developer",
        'R tags: ["api", "validation", "compatibility"],
    },

    E.Api.Timeout.EXCEEDED: {
        message: "API request timeout",
        'CR 'Pub description: "The API request exceeded the configured timeout limit. The remote service did not respond in time.",
        'CR 'Pub hints: [
            "Increase timeout",
            "Optimize payload size",
            "Use async endpoints"
        ],
        'CR 'Dev hints: [
            "Check network latency",
            "Review timeout configuration"
        ],
        'R role: "Developer",
        'R tags: ["api", "performance"],
    },
}