Error Codes

Overview

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 for more on trace IDs.

Error code ranges

Range	Category	Retry?
1xxx	Client/Request Errors	No — fix the request
2xxx	Resource Errors	No — fix auth or resource reference
3xxx	Server Errors	Yes — retry with backoff
4xxx	Delivery Errors	Sometimes — depends on cause
5xxx	Attachment/File Errors	Sometimes — depends on cause

1xxx — Client/Request Errors

Code	Message	HTTP	Troubleshooting
1001	Missing required field	400	Check API docs for required fields.
1002	Phone number must be in E.164 format	400	Include country code with `+` prefix (e.g., `+14155551234`).
1003	Invalid request body	400	Validate JSON syntax. Set `Content-Type: application/json`.
1004	Invalid message content	400	Ensure parts array has valid `text`, `media`, or `link` parts. A `link` part must be the only part.
1005	Invalid parameter value	400	Review parameter against API spec.
1006	Cannot update direct message chats	409	Only group chats support updates.
1007	Rate limit exceeded	429	Wait for reset or contact support for higher limits. See Rate Limits.

2xxx — Resource Errors

Code	Message	HTTP	Troubleshooting
2001	Chat not found	404	Verify chat ID is correct UUID from `POST`/`GET /v3/chats`.
2002	Message not found	404	Verify message ID and chat access.
2003	Attachment not found	404	Verify attachment ID. Presigned URLs expire — ensure uploads complete in time.
2004	Unauthorized	401	Include valid Bearer token in Authorization header. See Authentication.
2005	Access denied	403	You do not have permission to access this resource.
2006	Phone number permission denied	403	Verify the phone is assigned to your account.
2007	Attachment not ready	404	Attachment is still processing. Wait a few seconds and retry.
2008	Recipient not allowed	403	In sandbox, recipients must message you first.
2009	The chat is still being created	409	Wait a few seconds and retry.
2010	Webhook subscription not found	404	Verify subscription ID from `POST`/`GET /v3/webhook-subscriptions`.
2011	Feature not available	403	Contact support to enable this feature.
2012	Contact card not found	404	No active contact card for this phone number.
2013	This chat is unavailable	409	Chat may have been left or deleted. You cannot interact with it after leaving.
2014	Contact card already exists	409	A contact card already exists for this phone number. Use `PATCH` to update it.
2015	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 handle retries automatically.

Code	Message	HTTP	Troubleshooting
3001	Server connection error	500	Retry after 1-5 seconds.
3002	Server operation failed	500	Retry after 1-5 seconds. If persistent, contact support with `trace_id`.
3003	Service connection error	500	Retry after 1-5 seconds.
3004	Service operation failed	500	Retry after 1-5 seconds. If persistent, contact support with `trace_id`.
3005	Network timeout	504	Retry after a short delay.
3006	Internal server error	500	If persistent, contact support with `trace_id`.
3007	Maximum delivery attempts exceeded	500	Check recipient availability and try again later.

4xxx — Delivery Errors

Code	Message	HTTP	Troubleshooting
4001	Delivery failed	500	Try sending again. If persistent, contact support with `trace_id`.
4002	Phone not available	500	Check phone connectivity status.
4003	Webhook delivery failed	500	Ensure endpoint is reachable and returns 2xx within 10s. See Webhooks.
4004	Service unavailable	503	Retry after 30 seconds.

5xxx — Attachment/File Errors

Code	Message	HTTP	Troubleshooting
5001	File upload failed	500	Retry the upload. Check file size limits. See Attachments.
5002	File download failed	500	Ensure URL is public, HTTPS, with valid SSL.
5003	Failed to generate file URL	500	Retry the request.
5004	Invalid file type	400	Supported types include JPEG, PNG, GIF, MP4, PDF. See supported types.
5005	File too large	400	Reduce or compress file before uploading. See file size limits.
5006	Content type mismatch	400	Ensure URL extension matches actual file type, or use pre-upload.
5007	Failed to download image from the provided URL	400	Ensure the URL is publicly accessible and returns a valid image.