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

# Response Codes & Errors

> Reference of HTTP status codes, error response formats, and common 400, 401, 403, 404, 429, and 500 errors returned by the X API for debugging.

export const Button = ({href, children}) => {
  return <div className="not-prose group">
    <a href={href}>
      <button className="flex items-center space-x-2.5 py-1 px-4 bg-primary-dark dark:bg-white text-white dark:text-gray-950 rounded-full group-hover:opacity-[0.9] font-medium">
        <span>
          {children}
        </span>
        <svg width="3" height="24" viewBox="0 -9 3 24" class="h-6 rotate-0 overflow-visible"><path d="M0 0L3 3L0 6" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"></path></svg>
      </button>
    </a>
  </div>;
};

The X API uses standard HTTP status codes. Successful requests return 2xx codes; errors return 4xx or 5xx codes with details in the response body.

***

## HTTP status codes

### Success codes

| Code    | Meaning    | Description                                     |
| :------ | :--------- | :---------------------------------------------- |
| **200** | OK         | Request successful                              |
| **201** | Created    | Resource created (POST requests)                |
| **204** | No Content | Success with no response body (DELETE requests) |

### Client error codes

| Code    | Meaning           | Common causes                                              |
| :------ | :---------------- | :--------------------------------------------------------- |
| **400** | Bad Request       | Invalid JSON, malformed query, missing required parameters |
| **401** | Unauthorized      | Invalid or missing authentication credentials              |
| **403** | Forbidden         | Valid auth but no permission for this resource or action   |
| **404** | Not Found         | Resource doesn't exist or has been deleted                 |
| **409** | Conflict          | Stream has no rules (filtered stream only)                 |
| **429** | Too Many Requests | Rate limit or usage cap exceeded                           |

### Server error codes

| Code    | Meaning               | What to do                                   |
| :------ | :-------------------- | :------------------------------------------- |
| **500** | Internal Server Error | Wait and retry; check [status page](/status) |
| **502** | Bad Gateway           | Wait and retry                               |
| **503** | Service Unavailable   | X is overloaded; wait and retry              |
| **504** | Gateway Timeout       | Wait and retry                               |

***

## Error response format

Error responses include structured details:

```json theme={null}
{
  "title": "Invalid Request",
  "detail": "The 'query' parameter is required.",
  "type": "https://api.x.com/2/problems/invalid-request"
}
```

| Field    | Description                         |
| :------- | :---------------------------------- |
| `type`   | URI identifying the error type      |
| `title`  | Short error description             |
| `detail` | Specific explanation for this error |

Additional fields may be present depending on the error type.

***

## Error types

| Type                              | Description                                 |
| :-------------------------------- | :------------------------------------------ |
| `about:blank`                     | Generic error (see HTTP status code)        |
| `.../invalid-request`             | Malformed request or invalid parameters     |
| `.../resource-not-found`          | Post, user, or other resource doesn't exist |
| `.../not-authorized-for-resource` | No access to private/protected content      |
| `.../client-forbidden`            | App not enrolled or lacks required access   |
| `.../usage-capped`                | Usage cap exceeded                          |
| `.../rate-limit-exceeded`         | Rate limit exceeded                         |
| `.../streaming-connection`        | Stream connection problem                   |
| `.../rule-cap`                    | Too many filtered stream rules              |
| `.../invalid-rules`               | Rule syntax error                           |
| `.../duplicate-rules`             | Rule already exists                         |

***

## Partial errors

Some requests can partially succeed. A 200 response may include both `data` and `errors`:

```json theme={null}
{
  "data": [
    {"id": "123", "text": "Hello"}
  ],
  "errors": [
    {
      "resource_id": "456",
      "resource_type": "tweet",
      "title": "Not Found Error",
      "detail": "Could not find tweet with id: [456].",
      "type": "https://api.x.com/2/problems/resource-not-found"
    }
  ]
}
```

This happens when requesting multiple resources and some are unavailable.

***

## Troubleshooting common errors

<Accordion title="401 Unauthorized">
  **Check your authentication:**

  * Verify you're using the correct authentication method for the endpoint
  * Ensure credentials haven't been regenerated
  * Check the `Authorization` header format
  * For OAuth 1.0a, verify signature calculation

  [Authentication guide →](/resources/fundamentals/authentication/overview)
</Accordion>

<Accordion title="403 Forbidden">
  **Check your access:**

  * Verify your app has access to this endpoint
  * Some endpoints require specific enrollment or approval
  * User-context endpoints need appropriate OAuth scopes
  * The resource may be private or protected
</Accordion>

<Accordion title="429 Too Many Requests">
  **Rate limited:**

  * Check `x-rate-limit-reset` header for when to retry
  * Implement exponential backoff
  * Consider caching responses
  * Spread requests across the time window

  [Rate limits guide →](/x-api/fundamentals/rate-limits)
</Accordion>

<Accordion title="400 Bad Request">
  **Fix your request:**

  * Validate JSON syntax
  * Check for missing required parameters
  * Verify parameter types (strings vs. numbers)
  * Escape special characters in queries
</Accordion>

<Accordion title="Missing expected posts">
  **Check these factors:**

  * Protected accounts' posts are only visible with authorization
  * Deleted posts return 404
  * Some posts are withheld in certain regions
  * Verify search query syntax is correct
</Accordion>

<Accordion title="Stream disconnections">
  **Handle reconnection:**

  * Implement automatic reconnect with backoff
  * Use recovery features for missed data
  * Check for full-buffer disconnects (client not consuming fast enough)
  * Verify at least one stream rule exists

  [Streaming guide →](/x-api/fundamentals/handling-disconnections)
</Accordion>

***

## Rate limit headers

Every response includes rate limit information:

```
x-rate-limit-limit: 900
x-rate-limit-remaining: 847
x-rate-limit-reset: 1705420800
```

| Header                   | Description                       |
| :----------------------- | :-------------------------------- |
| `x-rate-limit-limit`     | Max requests in current window    |
| `x-rate-limit-remaining` | Requests remaining                |
| `x-rate-limit-reset`     | Unix timestamp when window resets |

***

## Best practices

<CardGroup cols={2}>
  <Card title="Check status codes" icon="square-check">
    Always check HTTP status before parsing the response body.
  </Card>

  <Card title="Handle partial errors" icon="triangle-exclamation">
    Check for `errors` array even in 200 responses.
  </Card>

  <Card title="Implement retry logic" icon="arrows-rotate">
    Use exponential backoff for 429 and 5xx errors.
  </Card>

  <Card title="Log request details" icon="file-lines">
    Include request ID and timestamp for debugging.
  </Card>
</CardGroup>

***

## Getting help

When posting questions about errors, include:

* The API endpoint URL
* Request headers (sanitize credentials)
* Full error response
* What you expected to happen
* Steps you've tried

<CardGroup cols={2}>
  <Card title="Developer Forum" icon="comments" href="https://devcommunity.x.com">
    Ask questions and search solutions.
  </Card>

  <Card title="API Status" icon="signal" href="/status">
    Check for known issues.
  </Card>
</CardGroup>