> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synci.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The error response format, the status codes the API uses, and how to handle them.

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`:

```json theme={"dark"}
{
  "message": "Not found"
}
```

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

```json theme={"dark"}
{
  "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](/guides/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.