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

# Error Codes

> How to interpret error codes to your requests to the Talview Graph API

The API uses standard HTTP status codes to indicate the result of an authentication or request attempt. Below are the common error structures you may encounter.

***

## HTTP Status Codes

### 400 Bad Request

Returned when variables are missing or the request is malformed.

```json theme={null}
{
  "extensions": {
    "code": 400,
    "traceId": "06b0de7d2a"
  },
  "message": "expecting a value for non-nullable variable: \"external_id\""
}
```

### 401 Unauthorized

Returned when the access token is missing or invalid.

```json theme={null}
{
  "extensions": {
    "code": 401,
    "traceId": "..."
  },
  "message": "..."
}
```

**Resolution:** Re-authenticate to obtain a new access token.

### 403 Forbidden

Returned when the provided token is expired or does not have sufficient permissions.

```json theme={null}
{
  "extensions": {
    "code": 403,
    "traceId": "77020d7cb1"
  },
  "message": "Token has expired"
}
```

### 422 Unprocessable Entity

Returned when the request is well-formed but contains semantic errors or violates business rules (e.g., validation failures).

```json theme={null}
{
  "extensions": {
    "code": 422,
    "traceId": "93bad0e604"
  },
  "message": "Candidate Creation failed"
}
```

### 429 Too Many Requests

Returned when the request frequency exceeds the allowed rate limit.

```json theme={null}
{
  "extensions": {
    "code": 429,
    "traceId": "..."
  },
  "message": "..."
}
```

**Resolution:** Implement exponential backoff. For more details, see the [Rate Limiting](/graph-api-reference/rate-limiting) guide.

### 500 Internal Server Error

Returned when an unexpected error occurs on the Talview server.

```json theme={null}
{
  "extensions": {
    "code": 500,
    "traceId": "93bad0e604"
  },
  "message": "Internal Server Error"
}
```

### 502 Server Timed Out

Returned when an upstream service did not respond in time.

```json theme={null}
{
  "extensions": {
    "code": 502,
    "traceId": "..."
  },
  "message": "..."
}
```

***

## Business Logic Errors

In GraphQL, a business rule violation may return an HTTP 200 OK status, but the `success` field within the data block will be `false`.

```json theme={null}
{
  "data": {
    "booking_create": {
      "success": false,
      "error_message": "No available slots for selected date",
      "data": null
    }
  }
}
```

### Common Logical Error Codes

These specific strings are often returned within the `error_message` field or GraphQL `extensions` block to provide granular detail:

| Error                          | Description                                        | Resolution                                       |
| :----------------------------- | :------------------------------------------------- | :----------------------------------------------- |
| `VALIDATION_ERROR`             | Input data failed schema or logic checks.          | Review input parameters and constraints.         |
| `SLOT_UNAVAILABLE`             | The selected time slot is no longer available.     | Refresh slot availability and select a new slot. |
| `BOOKING_NOT_FOUND`            | The provided Booking ID does not exist.            | Verify the Booking ID is correct.                |
| `RESCHEDULE_NOT_ALLOWED`       | Reschedule request violates business policy.       | Check reschedule eligibility windows.            |
| `PAYMENT_REQUIRED`             | Payment is required before the action can proceed. | Process the required payment transaction.        |
| `IDENTITY_VERIFICATION_FAILED` | Identity documents or photo failed verification.   | Review document quality and retry.               |

***

## Best Practices

1. **Check `success` first:** Always evaluate the `success` boolean before attempting to access the `data` object.
2. **Handle Actionable Errors:** Display the `error_message` directly to users for errors like `SLOT_UNAVAILABLE`.
3. **Token Management:** Automatically handle 401/403 errors by refreshing the OAuth2 access token.
4. **Logging:** Log the `traceId` provided in the error response to assist Talview support in debugging.