Register routing-layer error codes 50205, 50305, 50306, 50405 - #265
Conversation
|
|
||
| "50010": "Ably's edge proxy service has encountered an unknown internal error whilst processing the request", | ||
| "50210": "Ably's edge proxy service received an invalid (bad gateway) response from the Ably platform", | ||
| "50305": "Ably's routing layer was unable to service this request", |
There was a problem hiding this comment.
Let's add 50205 and 50405 too, which are also set by the router in a similar place to 50305.
There was a problem hiding this comment.
Done — 50205 and 50405 are now included, along with 50306 which is raised in the same serveError switch and was also unregistered.
|
@JoaoDiasAbly I know this is an old one, but if we still think it's something we want to merge, it needs to be updated to now register the codes by creating a Markdown file in the errors/codes directory. |
ae9e380 to
142f78a
Compare
JoaoDiasAbly
changed the title
|
Reworked to the new registration process: the four codes are now registered as Markdown files in |
There was a problem hiding this comment.
Do you mind giving Claude a stab at writing the bodies too? I'm currently working on the bodies for all existing codes
d5abd0d to
96241e8
Compare
|
|
||
| ## What you should do | ||
|
|
||
| On the main endpoint (the default), usually nothing: traffic is directed away from a disabled region, and SDK retries reach a healthy one. On a [region-specific endpoint](https://ably.com/docs/platform/account/enterprise-customization#regional-routing-and-storage), switch to the main endpoint: that endpoint pins every attempt to the named region, including retries, so requests keep failing while it is disabled. If your application has to stay pinned to a region, [contact Ably support](https://ably.com/support). |
There was a problem hiding this comment.
This is bad advice, if the customer is using a region-specific endpoint it's typically because they have a regional placement constraint, so if they switch to the main endpoint and hit regions their account is not permitted in, then they'll get errors.
Also, customers don't "pin to a region", the regional routing pins to a geographic area spanning multiple regions, so the advice here should be similar to 50305, the SDK will retry and traffic will eventually stop hitting the disabled region (as we would have taken it out of DNS).
There was a problem hiding this comment.
I see... That makes sense, thanks for calling it out. Fixed now
|
|
||
| ## Why it happens | ||
|
|
||
| Ably occasionally takes a region out of service temporarily, for example to protect the platform during an incident. A disabled region rejects the requests that reach it rather than redirecting them elsewhere. |
There was a problem hiding this comment.
It's never to protect the platform, it's always to prevent disruption when services in a region are not functioning correctly, often due to reasons outside out control.
There was a problem hiding this comment.
Overlooked that wording, thanks. Fixed
These codes are raised by the frontdoor router's serveError path when it cannot complete a request: connection refused upstream (50205), an unexpected error (50305), the target region being administratively disabled (50306), and an upstream timeout (50405). Registered via one Markdown file per code in errors/codes/, per the current registration process; protocol/errors.json is regenerated from the registry. Each code carries a detail-page body in the three-section format from errors/guidelines.md. Message strings and HTTP statuses are taken from the raising code in the realtime repo, and the retry guidance from the SDK spec: a 500-504 response or a request timeout qualifies for a retry against a fallback endpoint (RSC15l), an endpoint that names a region has no fallbacks outside it (REC2c2), and REST publishes are idempotent by default from SDK v1.2 (TO3n), so an automatic retry cannot duplicate a message. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
96241e8 to
09cd708
Compare
2 participants
https://ably.atlassian.net/browse/REA-2121
Reworked from the original one-line edit of
protocol/errors.json(which is now generated and must not be edited by hand) to the current registration process: one Markdown file per code inerrors/codes/, withprotocol/errors.jsonregenerated vianpm run generate:errors.Registers the four codes raised by the frontdoor router's
serveErrorpath (verified againstrealtimego/realtime/roles/frontdoor/router/request_handler.go):rejectForSiteDisabled)50205 and 50405 are included per @lmars's review; 50306 is raised in the same switch and was also unregistered, so it is included too.
Bodies
Per @lmars's latest review, all four codes now carry a detail-page body in the three-section format used by #352 (What you should do → Why it happens → What you'll see). Facts were checked against source rather than written from memory:
serveErrorinrequest_handler.go.500 <= code <= 504response or a request timeout qualifies for a retry against a fallback endpoint (RSC15l), so for 50205/50305/50405 the answer is "usually nothing, the SDK retries".REC2c2/REC2c4), so the request keeps failing until the region is re-enabled. The pre-existing 50306 body was also rewritten to satisfy the no-em-dash rule added toerrors/guidelines.mdin errors: Add bodies for all error codes with an FAQ page #352.TO3n), so an automatic retry cannot duplicate the message.Scope stays on this PR's four codes: the sibling edge-proxy codes (50010, 50210, 50310, 50410) are still body-less on
mainand belong to the wider sweep.protocol/errorsHelp.jsonalready contains an entry for 50305 (added separately in 2288fb9), so no change is needed there. Rebased ontomainand squashed to a single commit;npm run lint,validate:errors,validate:errors-json, thegenerate:errorsdrift check andnpm testall pass locally.🤖 Generated with Claude Code