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

# Error Codes

> Complete reference of API error codes with descriptions and resolution steps

All API errors follow a consistent format:

```json theme={null}
{
  "success": false,
  "statusCode": 404,
  "message": "Contact does not exist",
  "code": "CONTACT_NOT_FOUND"
}
```

Validation errors include field-level details:

```json theme={null}
{
  "success": false,
  "statusCode": 400,
  "message": "Validation failed",
  "code": "INVALID_INPUT",
  "errors": {
    "email": "email should not be empty"
  }
}
```

***

## Authentication Errors

| Code              | HTTP | Message                    | Resolution                                                                                              |
| ----------------- | ---- | -------------------------- | ------------------------------------------------------------------------------------------------------- |
| `INVALID_API_KEY` | 401  | Invalid or missing API key | Check that you're sending a valid `sk_live_*` or `sk_test_*` key in the `Authorization: Bearer` header. |
| `FORBIDDEN`       | 403  | Insufficient permissions   | Your API key doesn't have access to this resource.                                                      |

## Resource Errors

| Code                        | HTTP | Message                                     | Resolution                                                                                     |
| --------------------------- | ---- | ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `CONTACT_NOT_FOUND`         | 404  | Contact does not exist                      | Verify the contact ID. The contact may have been deleted in the connected CRM.                 |
| `LEAD_NOT_FOUND`            | 404  | Lead does not exist                         | Verify the lead ID. Not all providers support leads natively.                                  |
| `MEETING_NOT_FOUND`         | 404  | Meeting does not exist                      | Verify the meeting ID.                                                                         |
| `PROVIDER_NOT_FOUND`        | 404  | Provider does not exist                     | Check the provider slug.                                                                       |
| `CONNECTION_NOT_FOUND`      | 404  | No active connection found                  | The end user hasn't connected this provider. Use the Connect widget to establish a connection. |
| `END_USER_NOT_FOUND`        | 404  | End user does not exist                     | Verify the `endUserId` used when creating the connect token.                                   |
| `CONNECTION_ALREADY_EXISTS` | 409  | Connection already exists for this provider | An active connection already exists for this end user and provider.                            |

## Validation Errors

| Code                   | HTTP | Message                                 | Resolution                                                                                                               |
| ---------------------- | ---- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `INVALID_INPUT`        | 400  | Validation failed                       | Check the `errors` field for specific field-level failures.                                                              |
| `MISSING_REQUIRED`     | 400  | Required field is missing               | Include all required fields in your request.                                                                             |
| `MISSING_PROVIDER`     | 400  | Query parameter ?provider is required   | Add `?provider=hubspot` (or another slug) to your request URL.                                                           |
| `UNSUPPORTED_RESOURCE` | 400  | Provider does not support this resource | Not all providers support all resources.                                                                                 |
| `INVALID_DATE_RANGE`   | 400  | End date must be after start            | Ensure `endDate` is after `startDate`.                                                                                   |
| `INVALID_ISO_DATE`     | 400  | Query param must be ISO-8601            | The `created_after` / `created_before` filters must be in ISO-8601 format (e.g. `2026-05-11` or `2026-05-11T23:59:59Z`). |

## Method Not Allowed (405)

| Code                 | HTTP | Message                                                      | Resolution                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| -------------------- | ---- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `METHOD_NOT_ALLOWED` | 405  | Operation `<resource>.<op>` is not supported by `<provider>` | The chosen provider doesn't expose this operation for the resource. For example, financial reports (`balance_sheet`, `income_statement`, `cash_flow_statement`) and read-only resources (`address`, `phone_number`, `general_ledger_transaction`, `transaction`, `bank_feed_account`, `bank_feed_transaction`) only support list and get. `company_info` is update-only — it cannot be created or deleted. See the provider's integration page for the full compatibility matrix. |

## Provider Errors

These occur when communicating with the connected CRM or accounting provider.

| Code                    | HTTP | Message                                   | Resolution                                                                          |
| ----------------------- | ---- | ----------------------------------------- | ----------------------------------------------------------------------------------- |
| `PROVIDER_ERROR`        | 502  | Provider returned an error                | The provider returned an unexpected error. Retry the request.                       |
| `PROVIDER_RATE_LIMITED` | 429  | Provider rate limit exceeded              | The provider's rate limit was hit. Respect the `Retry-After` header.                |
| `PROVIDER_UNAVAILABLE`  | 503  | Provider is temporarily unavailable       | The provider is down. Retry with exponential backoff.                               |
| `CIRCUIT_OPEN`          | 503  | Circuit breaker is open for this provider | Too many consecutive failures. Will auto-recover — retry after the indicated time.  |
| `PROVIDER_AUTH_FAILED`  | 502  | Provider authentication failed            | The user's OAuth tokens are invalid. They need to reconnect via the Connect widget. |
| `NEEDS_REAUTH`          | 403  | Connection requires re-authentication     | The OAuth token expired and couldn't be refreshed. Prompt the user to reconnect.    |

## Server Errors

| Code                  | HTTP | Message                         | Resolution                                                           |
| --------------------- | ---- | ------------------------------- | -------------------------------------------------------------------- |
| `INTERNAL_ERROR`      | 500  | Something went wrong            | Unexpected error. Retry the request. If persistent, contact support. |
| `SERVICE_UNAVAILABLE` | 503  | Service temporarily unavailable | The platform is under maintenance. Retry with backoff.               |

***

## HTTP Status Code Summary

| Status | Meaning                                                                               |
| ------ | ------------------------------------------------------------------------------------- |
| `200`  | OK — successful GET, PUT, PATCH, DELETE                                               |
| `201`  | Created — successful POST                                                             |
| `400`  | Bad Request — validation error or missing parameter                                   |
| `401`  | Unauthorized — invalid or missing API key                                             |
| `403`  | Forbidden — connection needs re-auth                                                  |
| `404`  | Not Found — resource doesn't exist                                                    |
| `405`  | Method Not Allowed — operation not supported by the chosen provider for this resource |
| `409`  | Conflict — duplicate resource                                                         |
| `429`  | Too Many Requests — rate limit exceeded                                               |
| `500`  | Internal Server Error                                                                 |
| `502`  | Bad Gateway — provider communication error                                            |
| `503`  | Service Unavailable — provider or platform down                                       |