An error answers with an HTTP status and a JSON error object: a code, a message, and for some errors data. The code is stable, so your software can act on it; the message is for people, and its wording can change.
{
"error": {
"code": "permission-denied",
"message": "Missing required scope: invoices:read"
}
}Status codes
| Status | Code | When |
|---|---|---|
| 400 | invalid-argument |
A parameter, the body or a cursor is invalid; data lists the issues of a parameter or the body. |
| 401 | unauthenticated |
The key is missing, unknown, revoked or expired. |
| 403 | permission-denied |
The key lacks the scope, or its user lacks the permission in the workspace. |
| 404 | not-found |
The resource does not exist. |
| 409 | aborted or already-exists |
A rule of Sway refused the operation, such as a suspended workspace; data.name names the rule. |
| 429 | resource-exhausted, or no JSON body |
Too many requests: see the rate limit below. |
| 500 | internal or failed-precondition |
An unexpected error, or a resource that is not in the state the operation needs. Production hides the message of an unexpected error. |
| 503 | unavailable |
A service that Sway needs is unavailable for a moment. |
The details of a refusal
When a rule of Sway refuses an operation, data carries the name of that rule, which stays the same when the message changes, and the trace of the request when there is one. Give the trace to the support team when you ask about an error.
{
"error": {
"code": "aborted",
"message": "Workspace is suspended",
"data": {"name": "business/workspace-suspended", "trace": "…"}
}
}A workspace is suspended once its subscription has ended. Every call on its data then answers 409 with business/workspace-suspended, reads included, until the subscription is active again.
Rate limit
Sway accepts up to 600 requests a minute from each IP address. Above that, it answers 429, without a JSON body, until the minute is over. Every program that calls from the same address shares this limit.
Retry safely
- Retry a
429or a503after a pause, and wait longer after each attempt. - Do not repeat a
400,401,403or404as it is: fix the request, the key or its scopes first. - Before you repeat a write that timed out or answered
500, read the resource back: the first attempt may have changed it already.