Error codes
HTTP handlers return JSON for service-level errors. API Gateway can still emit its own small error bodies before Lambda runs.
The only cross-service invariant is that callers must handle a JSON object with a message or error field. New or edited handlers should include requestId and success: false for Lambda-originated errors, but older handlers are not fully uniform.
Status codes
| Status | Meaning |
|---|---|
200 | Success, warmup acknowledgement, or an intentional accepted/rejected webhook acknowledgement |
400 | Missing or invalid input, malformed JSON, schema validation failure |
401 | Handler-level token check failed, for example POST /leads/bot/queue |
403 | API Gateway rejected a missing/invalid X-Api-Key, WAF blocked the request, or a handler rejected an allowed-host check |
404 | Resource not configured or lookup target not found |
409 | Duplicate/conflicting write, for example an existing Cloudflare redirect |
429 | Leads token bucket, API Gateway usage-plan throttle, or WAF rate rule |
500 | Upstream failure, unhandled exception, or integration failure |
purge has a deliberate exception: POST /post/transition can return 200 with result: "rejected" for validation-style rejects because WordPress webhook delivery treats non-2xx responses as transport failures.
Error shape
{
"message": "BadRequest - Missing Request Attributes",
"requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"code": "InvalidInput",
"errors": [
{ "field": "phone_number", "message": "is required" }
],
"success": false
}| Field | Present | Notes |
|---|---|---|
message | common | Human-readable summary. API Gateway errors usually contain only this field. |
error | common in leads/rate-limit paths | Machine-readable or short error token. |
requestId | recommended for Lambda errors | Include it in support requests when present. |
code | service-specific | Machine-readable code, for example InvalidInput. |
errors | validation failures | Field-level detail or schema errors. |
success | common in newer handlers | false on error. |
Do not build clients that require every field in the example. Treat message, error, and requestId as optional unless the per-operation OpenAPI schema states otherwise.
API Gateway errors
Emitted before Lambda, fixed shape:
{ "message": "Forbidden" }{ "message": "Missing Authentication Token" }These responses are not controlled by the Lambda handler.
Rate-limit (429)
The in-handler token bucket used by leads inbound includes rate-limit headers:
HTTP/1.1 429 Too Many Requests
x-ratelimit-limit: 100
x-ratelimit-remaining: 0
x-ratelimit-reset: 1710000000000
x-ratelimit-resource: customer@example.comWAF and API Gateway usage-plan throttles can return 429 or 403 without these in-handler headers because the request never reaches the service code.