---
title: "Errors"
description: "Understand error codes and messages, and decide which failed requests are safe to retry."
url: "https://nov18-prod-sg.movespot.fyi/guides/errors"
image: "https://nov18-prod-sg.movespot.fyi/_og/d/c_Ocean.takumi,title_Errors,description_~VW5kZXJzdGFuZCBlcnJvciBjb2RlcyBhbmQgbWVzc2FnZXMsIGFuZCBkZWNpZGUgd2hpY2ggZmFpbGVkIHJlcXVlc3RzIGFyZSBzYWZlIHRvIHJldHJ5Lg,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiNDQjUzMjQifX19,p_Ii9ndWlkZXMvZXJyb3JzIg,s_9fzPEFvrhYs1CKXm.png"
---

# Errors

Understand error codes and messages, and decide which failed requests are safe to retry.

## [The error format](#the-error-format)

Every error response has the same shape, so you can handle all failures with one code path:

```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The 'limit' parameter must be between 1 and 100.",
    "request_id": "req_8k3j2l"
  }
}
```

The `code` is stable and safe to branch on. The `message` is for humans and can change. Include the `request_id` whenever you contact support.

## [Common status codes](#common-status-codes)

| Status                    | Meaning                                          | Retry?                      |
| :------------------------ | :----------------------------------------------- | :-------------------------- |
| 400 Bad Request           | Malformed request.                               | No. Fix the request.        |
| 401 Unauthorized          | Missing, revoked, or mistyped credential.        | No. Fix the credential.     |
| 403 Forbidden             | Your application isn't registered with this API. | No. Register first.         |
| 404 Not Found             | The resource doesn't exist.                      | No.                         |
| 422 Unprocessable Entity  | The request is valid JSON but fails validation.  | No. Fix the data.           |
| 429 Too Many Requests     | Rate limit exceeded.                             | Yes, after Retry-After.     |
| 500 Internal Server Error | Something failed on our side.                    | Rarely. Retry with backoff. |
| 503 Service Unavailable   | Temporary outage or maintenance.                 | Yes, with backoff.          |

The short version: `4xx` means something in your request needs to change. `5xx` means the failure was ours, and a retry may help.

## [Retry with backoff](#retry-with-backoff)

For the retryable statuses, use exponential backoff with jitter:

```javascript
async function requestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options)
    if (response.ok) return response

    const retryable = response.status === 429 || response.status >= 500
    if (!retryable || attempt === maxRetries) throw new Error(`Request failed: ${response.status}`)

    const retryAfter = Number(response.headers.get('Retry-After'))
    const delay = Math.max(Number.isFinite(retryAfter) ? retryAfter * 1000 : 0, 1000 * 2 ** attempt)
    await new Promise(resolve => setTimeout(resolve, delay))
  }
}
```

Only retry safe operations

A `GET` request is always safe to retry. Before retrying a `POST` that creates something, use an idempotency key. See [Idempotent requests](https://nov18-prod-sg.movespot.fyi/guides/idempotency).

## [Next steps](#next-steps)

### Rate limits

Read your remaining quota and back off before you hit `429`.

<https://nov18-prod-sg.movespot.fyi/guides/rate-limits>

### Idempotent requests

Retry safely after a timeout, so nothing happens twice.

<https://nov18-prod-sg.movespot.fyi/guides/idempotency>

### Get help

Search the guides for answers, or contact the team with your request ID for a faster answer.

<https://nov18-prod-sg.movespot.fyi/guides>