Errors

The Synci API uses conventional HTTP status codes. Codes in the 2xx range mean success, 4xx means something was wrong with the request, and 5xx means something went wrong on Synci's side.

Error response format

Errors return a JSON body with a human-readable message:

{
  "message": "Not found"
}

Validation failures (422) additionally include an errors map with per-field messages:

{
  "message": "The url field must be a valid URL.",
  "errors": {
    "url": [
      "The url field must be a valid URL."
    ]
  }
}

Status codes

Code	Meaning
`200 OK`	The request succeeded.
`201 Created`	The resource was created.
`204 No Content`	The request succeeded and there is nothing to return (typically deletes).
`400 Bad Request`	The request was malformed.
`401 Unauthorized`	Missing, expired, or revoked token.
`403 Forbidden`	The token is valid but lacks a required scope, or the action is not available on your plan.
`404 Not Found`	The resource does not exist, or it was not granted to this token. Synci deliberately returns `404` instead of `403` for ungranted resources so tokens cannot probe for data they were not given.
`409 Conflict`	The request cannot be performed in the resource's current state (for example, syncing an account that is inactive at the bank).
`422 Unprocessable Entity`	Validation failed; see the `errors` map.
`429 Too Many Requests`	You hit a rate limit; see Rate limits. The `message` explains which limit and, where applicable, when you can retry.
`500 Internal Server Error`	Something went wrong on our side. Safe to retry with backoff; contact support if it persists.

OAuth errors

The OAuth endpoints (/oauth/authorize, /oauth/token) return standard OAuth 2.0 error codes:

Error	Cause
`invalid_client`	Wrong or missing client credentials, or the token request was sent as JSON instead of `application/x-www-form-urlencoded`.
`invalid_grant`	Expired or already-used authorization code, mismatched `code_verifier`, or a rotated/revoked refresh token.
`invalid_scope`	A requested scope is not registered for your app.
`access_denied`	The user declined the authorization request (returned on the redirect).

Handling errors

Retry 429 and 5xx with exponential backoff. Honor the Retry-After header when present.

Do not retry 4xx (other than 429) without fixing the request.

Treat 401 on a previously working OAuth token as "access token expired": refresh and retry once. If the refresh also fails, the user has likely revoked your app and needs to authorize again.

Error response format#

Status codes#

OAuth errors#

Handling errors#

Error response format

Status codes

OAuth errors

Handling errors