> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.moveworks.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.moveworks.com/_mcp/server.

# Content Gateway Errors

> Standard error codes and format for the Moveworks Content Gateway

## Gateway Errors

All gateways should expose the following error codes to Moveworks. The error code and message format should follow exactly as below. The API gateway should make limited-to-no changes to error messages exposed by underlying systems.

```json title="Error Response Format"
{
    "error": {
        "code": "ERROR_CODE_IDENTIFIER",
        "message": "Description of the error."
    }
}
```

## Error Codes

### 400 `INPUT_VALIDATION_FAILED`

Moveworks submitted an invalid request to the gateway.

```json
{
  "error": {
      "code": "INPUT_VALIDATION_FAILED",
      "message": "Mandatory field not provided: submitted_by."
  }
}
```

### 401 `AUTHENTICATION_FAILED`

The provided credential by Moveworks is invalid or missing. This is NOT the same as authentication failing between the gateway and your downstream systems.

```json
{
  "error": {
      "code": "AUTHENTICATION_FAILED",
      "message": "Bearer token missing."
  }
}
```

### 404 `NOT_FOUND`

The resource identifier Moveworks is requesting is missing.

```json
{
  "error": {
      "code": "NOT_FOUND",
      "message": "Form ID 222 does not exist."
  }
}
```

### 429 `RATE_LIMIT_EXCEEDED`

Moveworks has exceeded the allowable number of requests per minute.

```json
{
  "error": {
      "code": "RATE_LIMIT_EXCEEDED",
      "message": "Rate limit exceeded."
  }
}
```

If your gateway enforces a rate limit, advertise it via response headers on every response. Moveworks reads these headers and proactively slows down its call rate when your remaining capacity drops below \~30% of your limit, without waiting for a `429`:

```yaml title="Rate Limit Headers (advisory; opt in when you enforce a rate limit)"
X-RateLimit-Limit: <max requests per window>
X-RateLimit-Remaining: <requests remaining in current window>
X-RateLimit-Reset: <seconds until rate limit fully resets>
```

Common header-name variants (`X-Rate-Limit-*`, RFC 9456 `RateLimit-*`) are also recognized. If you do not enforce a rate limit on your side, omit these headers entirely; Moveworks falls back to its baseline crawl pacing.

For the full throttling story (proactive vs reactive behavior, what Moveworks does with each header, capacity planning), see the [Operational Guide](/api-reference/content-gateway/operational-guide#how-do-i-throttle-moveworks-calls-to-my-gateway).

### 500 `INTERNAL_SERVER_ERROR`

Something went wrong in the gateway and threw an exception.

```json
{
  "error": {
      "code": "INTERNAL_SERVER_ERROR",
      "message": "NoneType has no attribute 'records'"
  }
}
```

### 502 `EXTERNAL_REST_ERROR`

Something went wrong between the gateway and your system. Should include the raw response from the source system's error.

```json
{
  "error": {
      "code": "EXTERNAL_REST_ERROR",
      "message": "Service Cloud rejected the request. Raw response: SOQL insertion failed. Can not set Case Owner to Contact record."
  }
}
```