Status codes and troubleshooting
What each failure means, which side it comes from, and the first thing to check.
These pages describe ShellOrbit as it runs today. Breaking changes to the HTTP API are announced before they ship, and existing request and response shapes stay supported.
The event never arrived
Check the provider’s own delivery log first. If the provider shows a failure to reach us, the cause is almost always the URL: a typo in the endpoint id, a deleted endpoint, or a custom domain whose CNAME no longer resolves.
If the provider shows a 429 from us, you are over the ingest rate on that endpoint or over a free plan limit. See limits.
The event arrived but was never delivered
Look at the event’s state:
| State | Meaning | First thing to check |
|---|---|---|
received | Stored, no destination configured | Add a destination to the endpoint |
queued | Waiting for a worker or for its next retry | The attempt trail shows the next scheduled time |
paused | Endpoint delivery is paused | Resume the endpoint |
retrying | At least one attempt failed | The response code and body excerpt on the last attempt |
failed | Every attempt is exhausted | Fix the handler, then replay |
delivered | A 2xx was received | Nothing |
Common destination failures
| What we record | Usual cause |
|---|---|
timeout after 15 seconds | Your handler is doing slow work before responding. Acknowledge first, work after |
| 502 or 503 | The destination was restarting or behind a proxy that was not ready |
| 401 or 403 | Your handler rejected the request, often signature verification against a re-serialised body |
| 404 | The route moved or the deploy removed it |
tls_error | Expired or misconfigured certificate on the destination |
dns_error | The hostname stopped resolving |
| 410 | Treated as permanent, no further attempts |
Signature verification keeps failing
Verify against the raw request body, before any JSON parsing. Re-serialising changes whitespace and key order, which changes the bytes and therefore the hash. Also confirm the timestamp tolerance is not too tight for a retried delivery, since a retry can arrive minutes after the signed timestamp.
The same event keeps arriving
Delivery is at least once. If your handler is slow to answer, we may time out and retry while your side is still processing. Answer with a 2xx as soon as the event is stored, and key your writes on the event id.
I need help
Send the endpoint id, one event id, and the timestamp to support@shellorbit.com. Those three details let us read the same records you are looking at, and the first reply will contain an answer rather than a request for more information.