# Errors

> The error bodies and HTTP statuses of the Stacksync API, and which errors to retry

Source: https://docs.stacksync.com/api-reference/errors

A failed request answers a 4xx status and a JSON body that names the problem.

## Error body

Operations of the current conventions answer:

```json
{ "error": "<kind of error>", "msg": "<what went wrong>", "field": "<parameter or field at fault, or null>" }
```

| Field   | Meaning                                                 |
| ------- | ------------------------------------------------------- |
| `error` | The kind of error, stable enough to branch on           |
| `msg`   | What went wrong, in plain words, for logs and people    |
| `field` | The parameter or body field at fault, when there is one |

The older operations of syncs, sync triggers, sync webhooks, sync issues and connection creation answer a body with at least `error`, holding the message:

```json
{ "error": "<what went wrong>" }
```

Each operation's page lists the statuses it answers and their body.

## Statuses

| Status | Meaning                                                                                                                                                                        | What to do                                                                               |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| 400    | The request is invalid: a parameter or body field is missing, of the wrong type or out of range. With `error` `Unexpected Error`, Stacksync could not complete a valid request | Fix the request; `field` names the culprit. `Unexpected Error` is temporary: retry later |
| 403    | Authentication or permission failure. The API never answers 401                                                                                                                | See [Authentication](/api-reference/authentication#authentication-errors)                |
| 404    | The resource doesn't exist in this workspace and region                                                                                                                        | Check the id and the `region`                                                            |
| 409    | The request conflicts with the resource's state, or a request with the same `Idempotency-Key` is still running                                                                 | Read the resource, or wait and retry                                                     |
| 422    | The `Idempotency-Key` was already used with a different request. Some older operations also answer 422 when the request fails validation; their pages list it                  | Use a new key for a new request, or fix the request                                      |

Most answers, errors included, carry an `X-Request-Id` header. Quote it when you contact support.

## When to retry

Retry the same request, with an increasing delay between attempts, only when:

* the answer is **400** with `error` `Unexpected Error`: a temporary failure on Stacksync's side;
* the answer is **409** because a request with the same `Idempotency-Key` is still running.

For creates, retry with the same `Idempotency-Key`, so a retry never creates the resource twice. Every other error answers the same until the request changes: fix the request, the key or the `region` instead of retrying.

No rate limit is published.