Wrong region
type: https://docs.onearly.com/errors/wrong-region
status: 421 Misdirected Request
code: WRONG_REGION
Every OnEarly account and group has a home region, where its data is kept. You call one global address, https://api.onearly.com, and OnEarly serves each request from the right home region.
Occasionally a request reaches a region that doesn't hold the data it needs, for example just after an account has moved. Instead of answering, that region refuses the request with 421 WRONG_REGION and tells you where to send it. Nothing was changed by the refused request.
The response
The body uses the problem details format (RFC 9457) with Content-Type: application/problem+json:
{
"type": "https://docs.onearly.com/errors/wrong-region",
"title": "Your account is served from another region",
"status": 421,
"code": "WRONG_REGION",
"region": "<home region>",
"base_url": "<address of your home region>"
}
| Field | Description |
|---|---|
type | This page's address. Identifies the problem. |
title | A short, human-readable summary. |
status | Always 421. |
code | Always WRONG_REGION. Match on this or on type. |
region | The home region that holds the data. |
base_url | The address to send the request to instead. |
placement_epoch | Identifies the placement the refusing region used. You don't need to interpret it; log it with the error. |
region, base_url and placement_epoch appear when the refusing region knows them. The same values are sent as headers:
| Header | Same as |
|---|---|
OE-Region | region |
OE-Region-Url | base_url |
OE-Placement-Epoch | placement_epoch |
How to retry
Follow a 421 once.
- Read
base_urlfrom the body, orOE-Region-Urlfrom the headers. - Resend the request to that address, keeping the same method, path, query, body and idempotency key.
- If that works, carry on. If you use OAuth, refresh your access token so later requests carry your current home region.
- If the retry returns
421again, stop. Don't keep following. Show or log an error that includes the response body.
If the response has no base_url and no OE-Region-Url, don't retry. Report the error.
Only follow base_url values that point at an onearly.com address. Send your credential nowhere else.
Don't save base_url and send future requests there. Keep using https://api.onearly.com. Your home region can change, and the global address always knows where it is.
Related responses
| Response | Meaning | What to do |
|---|---|---|
503 PLACEMENT_MOVING | Your account or group is being moved between regions. | Wait for Retry-After, then retry the same address. |
503 REGION_UNAVAILABLE | The region that holds the data is temporarily unavailable. | Wait, then retry the same address. |
The MCP server never answers 421.