--- title: Error Codes | API Docs description: Complete reference of Linq API error codes with troubleshooting guides. --- All API errors return a consistent JSON envelope with a nested `error` object, a `success: false` flag, and a top-level `trace_id` for debugging. The `error` object includes a `doc_url` linking directly to the error code reference page. ``` { "success": false, "error": { "status": 400, "code": 1001, "message": "Missing required field", "doc_url": "https://docs.linqapp.com/error/codes/1xxx/1001/" }, "trace_id": "2eff5df5c6f688733c007523c4d61cd9" } ``` On `429` responses, `error` also includes a `retry_after` integer (seconds to wait before retrying). > **Tip:** Always include the `trace_id` from error responses when contacting Linq support. See [Debugging](/guides/platform/debugging/index.md) for more on trace IDs. ## Error code ranges | Range | Category | Retry? | | ------------------------------------ | ---------------------- | ----------------------------------- | | [1xxx](#1xxx--clientrequest-errors) | Client/Request Errors | No — fix the request | | [2xxx](#2xxx--resource-errors) | Resource Errors | No — fix auth or resource reference | | [3xxx](#3xxx--server-errors) | Server Errors | Yes — retry with backoff | | [4xxx](#4xxx--delivery-errors) | Delivery Errors | Sometimes — depends on cause | | [5xxx](#5xxx--attachmentfile-errors) | Attachment/File Errors | Sometimes — depends on cause | ## 1xxx — Client/Request Errors | Code | Message | HTTP | Troubleshooting | | --------------------------------------- | ------------------------------------ | ---- | -------------------------------------------------------------------------------------------------------------- | | [1001](/error/codes/1xxx/1001/index.md) | Missing required field | 400 | Check API docs for required fields. | | [1002](/error/codes/1xxx/1002/index.md) | Phone number must be in E.164 format | 400 | Include country code with `+` prefix (e.g., `+14155551234`). | | [1003](/error/codes/1xxx/1003/index.md) | Invalid request body | 400 | Validate JSON syntax. Set `Content-Type: application/json`. | | [1004](/error/codes/1xxx/1004/index.md) | Invalid message content | 400 | Ensure parts array has valid `text`, `media`, or `link` parts. A `link` part must be the only part. | | [1005](/error/codes/1xxx/1005/index.md) | Invalid parameter value | 400 | Review parameter against API spec. | | [1006](/error/codes/1xxx/1006/index.md) | Cannot update direct message chats | 409 | Only [group chats](/guides/chats/group-chats/index.md) support updates. | | [1007](/error/codes/1xxx/1007/index.md) | Rate limit exceeded | 429 | Wait for reset or contact support for higher limits. See [Rate Limits](/guides/platform/rate-limits/index.md). | ## 2xxx — Resource Errors | Code | Message | HTTP | Troubleshooting | | --------------------------------------- | -------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | [2001](/error/codes/2xxx/2001/index.md) | Chat not found | 404 | Verify chat ID is correct UUID from `POST`/`GET /v3/chats`. | | [2002](/error/codes/2xxx/2002/index.md) | Message not found | 404 | Verify message ID and chat access. | | [2003](/error/codes/2xxx/2003/index.md) | Attachment not found | 404 | Verify attachment ID. Presigned URLs expire — ensure uploads complete in time. | | [2004](/error/codes/2xxx/2004/index.md) | Unauthorized | 401 | Include valid Bearer token in Authorization header. See [Authentication](/getting-started/authentication/index.md). | | [2005](/error/codes/2xxx/2005/index.md) | Access denied | 403 | You do not have permission to access this resource. | | [2006](/error/codes/2xxx/2006/index.md) | Phone number permission denied | 403 | Verify the phone is assigned to your account. | | [2007](/error/codes/2xxx/2007/index.md) | Attachment not ready | 404 | Attachment is still processing. Wait a few seconds and retry. | | [2008](/error/codes/2xxx/2008/index.md) | Recipient not allowed | 403 | In sandbox, recipients must message you first. | | [2009](/error/codes/2xxx/2009/index.md) | The chat is still being created | 409 | Wait a few seconds and retry. | | [2010](/error/codes/2xxx/2010/index.md) | Webhook subscription not found | 404 | Verify subscription ID from `POST`/`GET /v3/webhook-subscriptions`. | | [2011](/error/codes/2xxx/2011/index.md) | Feature not available | 403 | Contact support to enable this feature. | | [2012](/error/codes/2xxx/2012/index.md) | Contact card not found | 404 | No active contact card for this phone number. | | [2013](/error/codes/2xxx/2013/index.md) | This chat is unavailable | 409 | Chat may have been left or deleted. You cannot interact with it after leaving. | | [2014](/error/codes/2xxx/2014/index.md) | Contact card already exists | 409 | A contact card already exists for this phone number. Use `PATCH` to update it. | | [2015](/error/codes/2xxx/2015/index.md) | Operation conflicts with current state | 409 | The resource is in a state that conflicts with this operation (for example, editing a message that has already been deleted). Refresh state and retry. | ## 3xxx — Server Errors These are transient errors. Retry with exponential backoff (start at 1 second, max 30 seconds). The official [SDKs](/getting-started/sdks/index.md) handle retries automatically. | Code | Message | HTTP | Troubleshooting | | --------------------------------------- | ---------------------------------- | ---- | ------------------------------------------------------------------------ | | [3001](/error/codes/3xxx/3001/index.md) | Server connection error | 500 | Retry after 1-5 seconds. | | [3002](/error/codes/3xxx/3002/index.md) | Server operation failed | 500 | Retry after 1-5 seconds. If persistent, contact support with `trace_id`. | | [3003](/error/codes/3xxx/3003/index.md) | Service connection error | 500 | Retry after 1-5 seconds. | | [3004](/error/codes/3xxx/3004/index.md) | Service operation failed | 500 | Retry after 1-5 seconds. If persistent, contact support with `trace_id`. | | [3005](/error/codes/3xxx/3005/index.md) | Network timeout | 504 | Retry after a short delay. | | [3006](/error/codes/3xxx/3006/index.md) | Internal server error | 500 | If persistent, contact support with `trace_id`. | | [3007](/error/codes/3xxx/3007/index.md) | Maximum delivery attempts exceeded | 500 | Check recipient availability and try again later. | ## 4xxx — Delivery Errors | Code | Message | HTTP | Troubleshooting | | --------------------------------------- | ----------------------- | ---- | --------------------------------------------------------------------------------------------------- | | [4001](/error/codes/4xxx/4001/index.md) | Delivery failed | 500 | Try sending again. If persistent, contact support with `trace_id`. | | [4002](/error/codes/4xxx/4002/index.md) | Phone not available | 500 | Check phone connectivity status. | | [4003](/error/codes/4xxx/4003/index.md) | Webhook delivery failed | 500 | Ensure endpoint is reachable and returns 2xx within 10s. See [Webhooks](/guides/webhooks/index.md). | | [4004](/error/codes/4xxx/4004/index.md) | Service unavailable | 503 | Retry after 30 seconds. | ## 5xxx — Attachment/File Errors | Code | Message | HTTP | Troubleshooting | | --------------------------------------- | ---------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------- | | [5001](/error/codes/5xxx/5001/index.md) | File upload failed | 500 | Retry the upload. Check file size limits. See [Attachments](/guides/messaging/attachments/index.md). | | [5002](/error/codes/5xxx/5002/index.md) | File download failed | 500 | Ensure URL is public, HTTPS, with valid SSL. | | [5003](/error/codes/5xxx/5003/index.md) | Failed to generate file URL | 500 | Retry the request. | | [5004](/error/codes/5xxx/5004/index.md) | Invalid file type | 400 | Supported types include JPEG, PNG, GIF, MP4, PDF. See [supported types](/guides/messaging/attachments#supported-file-types/index.md). | | [5005](/error/codes/5xxx/5005/index.md) | File too large | 400 | Reduce or compress file before uploading. See [file size limits](/guides/messaging/attachments#file-size-limits/index.md). | | [5006](/error/codes/5xxx/5006/index.md) | Content type mismatch | 400 | Ensure URL extension matches actual file type, or use [pre-upload](/guides/messaging/attachments#pre-upload-up-to-100mb/index.md). | | [5007](/error/codes/5xxx/5007/index.md) | Failed to download image from the provided URL | 400 | Ensure the URL is publicly accessible and returns a valid image. |