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

# Errors

> Understand error codes and how to handle them in your integration.

All API errors return a consistent JSON structure with a machine-readable code, a human-readable message, a link to relevant documentation, and a `requestId` to include when reporting issues.

```json theme={"system"}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested exercise could not be found.",
    "docs": "https://docs.ascendapi.com/errors/code/NOT_FOUND",
    "requestId": "req_12345"
  }
}
```

<Note>
  Always include the `requestId` when contacting support. It helps us trace the exact request on our end.
</Note>

***

## Error Codes

***

### 400 Bad Request

**Code:** `BAD_REQUEST`

The request was malformed or contained invalid parameters. Check your query parameters, request body, and data types before retrying.

```json theme={"system"}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid value for parameter 'difficulty'. Expected one of: beginner, intermediate, advanced.",
    "docs": "https://docs.ascendapi.com/errors/code/BAD_REQUEST",
    "requestId": "req_12345"
  }
}
```

***

### 401 Unauthorized

**Code:** `UNAUTHORIZED`

No valid API key was provided. Make sure you are sending the `X-RapidAPI-Key` header with every request.

```json theme={"system"}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key.",
    "docs": "https://docs.ascendapi.com/errors/code/UNAUTHORIZED",
    "requestId": "req_12345"
  }
}
```

<Tip>
  If you are subscribed on RapidAPI but still getting 401s, go to the **App** tab in the playground and verify your key is correct.
</Tip>

***

### 403 Forbidden

**Code:** `FORBIDDEN`

Your API key is valid but does not have access to this resource. This usually means the endpoint or feature requires a higher plan.

```json theme={"system"}
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Your current plan does not include access to this endpoint.",
    "docs": "https://docs.ascendapi.com/errors/code/FORBIDDEN",
    "requestId": "req_12345"
  }
}
```

***

### 404 Not Found

**Code:** `NOT_FOUND`

The requested resource does not exist. Double-check the `exerciseId` or endpoint path.

```json theme={"system"}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "No exercise found with id 'edb_invalid'.",
    "docs": "https://docs.ascendapi.com/errors/code/NOT_FOUND",
    "requestId": "req_12345"
  }
}
```

***

### 405 Method Not Allowed

**Code:** `METHOD_NOT_ALLOWED`

The HTTP method used is not supported for this endpoint. All ascendapi.com `GET`.

```json theme={"system"}
{
  "error": {
    "code": "METHOD_NOT_ALLOWED",
    "message": "POST is not allowed on this endpoint.",
    "docs": "https://docs.ascendapi.com/errors/code/METHOD_NOT_ALLOWED",
    "requestId": "req_12345"
  }
}
```

***

### 409 Conflict

**Code:** `CONFLICT`

The request conflicts with the current state of the server.

```json theme={"system"}
{
  "error": {
    "code": "CONFLICT",
    "message": "A conflict occurred with the current resource state.",
    "docs": "https://docs.ascendapi.com/errors/code/CONFLICT",
    "requestId": "req_12345"
  }
}
```

***

### 412 Precondition Failed

**Code:** `PRECONDITION_FAILED`

This error occurs when your request is valid, but a precondition required to fulfill it is not met. Unlike validation errors where your input is invalid, precondition failures indicate that the system or resource is not configured correctly to handle your request.

```json theme={"system"}
{
  "error": {
    "code": "PRECONDITION_FAILED",
    "message": "Required precondition was not met.",
    "docs": "https://docs.ascendapi.com/errors/code/PRECONDITION_FAILED",
    "requestId": "req_12345"
  }
}
```

***

### 429 Too Many Requests

**Code:** `TOO_MANY_REQUESTS`

You have exceeded the rate limit for your plan. Free plans are limited to 1,000 requests per hour. See [Rate Limiting](/features/ratelimiting) for details.

```json theme={"system"}
{
  "error": {
    "code": "TOO_MANY_REQUESTS",
    "message": "Rate limit exceeded. Please wait before making further requests.",
    "docs": "https://docs.ascendapi.com/errors/code/TOO_MANY_REQUESTS",
    "requestId": "req_12345"
  }
}
```

***

### 500 Internal Server Error

**Code:** `INTERNAL_SERVER_ERROR`

This error occurs when there is an issue with the server. If you have received this error, please contact support immediately. We constantly monitor our servers and will resolve the issue as soon as possible, but sometimes the error you encounter may be due to a temporary issue or we are not aware of if at the moment.

```json theme={"system"}
{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred. Please try again later.",
    "docs": "https://docs.ascendapi.com/errors/code/INTERNAL_SERVER_ERROR",
    "requestId": "req_12345"
  }
}
```

***

## RapidAPI-Specific Errors

When accessing the API through RapidAPI, you may encounter additional error responses returned by the RapidAPI gateway before reaching our servers.

| Status | Cause                        | Resolution                                                    |
| ------ | ---------------------------- | ------------------------------------------------------------- |
| `401`  | Invalid API key.             | Verify you are using the correct key                          |
| `403`  | Not subscribed to the API    | Subscribe at  [RapidAPI](https://rapidapi.com/user/ascendapi) |
| `429`  | RapidAPI plan quota exceeded | Upgrade your plan or wait for the quota to reset              |
| `500`  | RapidAPI gateway error       | Retry the request. If it persists, contact us                 |

***

## Contact

If you encounter an error that is not listed here or need help debugging, reach out at [support@ascendapi.com](mailto:support@ascendapi.com).