API bad-day examples
What Luota returns when an ingest integration has an invalid token, oversized payload, duplicate retry, rate limit, alert-delivery problem, or support-correlation request id.
Invalid token
Luota rejects missing, mistyped, rotated, or monitor-mismatched ingest tokens with 401.
POST /v1/runs/start HTTP/1.1
X-Luota-Key: wfws1.redacted
Content-Type: application/json
{ "monitorId": "22222222-2222-4222-8222-222222222222", "externalRunId": "job-42" }{
"error": "Invalid ingest key"
}Capture the HTTP status and X-Request-Id. Do not log the ingest token.
Payload too large
Raw JSON bodies above the published ingest body limit are rejected before parsing with 413.
{
"code": "request_failed",
"error": "Request failed"
}Store large output in object storage and send a short URL or digest in the payload.
Rate limit
When a monitor token, workspace, or source IP exceeds the active ingest policy, Luota returns 429 and includes Retry-After when possible.
HTTP/1.1 429 Too Many Requests
Retry-After: 21
X-Request-Id: req-01HX...{
"error": "Rate limit exceeded",
"policy": "ingest.monitor_token.minute",
"retryAfterSeconds": 21,
"limit": 60
}Back off instead of retrying in a tight loop.
Duplicate and retry behavior
externalRunId is the idempotency key for run starts on a monitor. Re-sending the same run start should not create duplicate operator evidence. Success and failure calls are terminal: a successful run cannot later be marked failed, and a failed run cannot later be marked successful.
For network uncertainty, retry the same externalRunId and keep the response body in job logs. For state conflicts, treat 409 as a signal that another completion path already won.
Alert delivery failed or retrying
An ingest call can land and open the right incident while the alert route itself is still unproven. Treat these as separate facts:
| State | Meaning | Operator action |
|---|---|---|
delivered | A durable email, webhook, or other route attempt reached the provider. | Keep the provider id and incident id in the packet. |
failed_retrying | The provider rejected or timed out, and Luota has another attempt scheduled. | Fix the route if the destination is wrong; otherwise watch the next attempt time. |
failed_terminal | The route exhausted its retry policy or is no longer deliverable. | Repair the destination and send a test alert before trusting the monitor. |
For a deliberate drill, configure a temporary webhook route that returns 503, close a run with /fail, and open the incident detail page. The packet should say the workflow failed and the alert route is retrying or blocked. Do not mark the drill trusted only because the ingest API returned 202.
Request id visibility
Every API response includes X-Request-Id. Log it with the status code and sanitized response body so support can correlate the request without seeing secrets or raw sensitive payloads.