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 the API docs for the required fields on the endpoint you are calling
1002	Phone number must be in E.164 format	400	Include the country code with a `+` prefix (e.g., `+14155551234` for a US number)
1003	Invalid request body	400	Validate your JSON syntax using a linter or validator
1004	Invalid message content	400	Ensure the `parts` array contains valid `text`, `media`, or `link` parts
1005	Invalid parameter value	400	Review the parameter against the API spec to confirm accepted values, formats, and constraints
1006	Cannot update direct message chats	409	Only group chats support updates — verify the chat you are trying to update is a group chat, not a direct message
1007	Rate limit exceeded	429	Respect the `Retry-After` interval before retrying the request.
1008	Invalid iMessage app message	400	`app.name` is required, and `app.team_id` must be 10 uppercase alphanumeric characters

2xxx — Resource Errors

Code	Message	HTTP	Troubleshooting
2001	Chat not found	404	Verify the chat ID is a correct UUID returned from `POST /v3/chats` or `GET /v3/chats`
2002	Message not found	404	Verify the message ID is correct
2003	Attachment not found	404	Verify the attachment ID is correct
2004	Unauthorized	401	Include a valid Bearer token in the `Authorization` header (e.g., `Authorization: Bearer your-api-key`)
2005	Access denied	403	Verify the resource (chat, attachment, subscription) belongs to your partner account.
2006	Phone number permission denied	403	Verify the phone number is assigned to your account
2007	Attachment not ready	404	Wait a few seconds and retry the request
2008	Recipient not allowed	403	In sandbox mode, recipients must message you first before you can send to them
2009	The chat is still being created	409	Wait a few seconds and retry the request
2010	Webhook subscription not found	404	Verify the subscription ID is a correct UUID returned from `POST /v3/webhook-subscriptions` or `GET /v3/webhook-subscriptions`
2011	Feature not available	403	Contact support to enable this feature for your account
2012	Contact card not found	404	Verify the phone number is in E.164 format and matches a line assigned to your account.
2013	This chat is unavailable	409	Check the chat status — you cannot interact with or perform actions on a chat after leaving it
2014	A contact card already exists for this phone number	409	Use `PATCH /v3/contact_card?phone_number={phone_number}` to update the existing card instead of `POST` to create a new one.
2015	Operation conflicts with current state	409	Refresh the resource before retrying (e.g., re-fetch the chat or message)
2016	Operation not supported in group chats	409	Open the 1:1 chat with the intended recipient and retry there
2017	Operation not supported on this chat’s service type	409	Check `service` on the chat before calling, and retry on a chat whose service supports the operation
2018	iMessage app messages can only be sent over iMessage	409	Omit `preferred_service` — it defaults to iMessage for app parts — or set it to `iMessage`
2019	Phone number not found	404	Verify the phone number ID against `GET /v3/phone_numbers` — it is the `id` of the line, not the number itself
2020	Reputation audit not found	404	Use the `audit_id` returned by `POST /v3/phone_numbers/{phoneNumber}/reputation_audit` — it is the only place an audit ID is issued
2021	Payment request not found	404	Verify the ID against `GET /v3/payment_requests` — it is the `id` from the create response, not the Stripe checkout session
2022	Contact card setup failed	500	Retry the same `POST` or `PATCH /v3/contact_card` call after a few seconds — this is a transient failure, not a bad request
2023	Operation requires a group chat	409	Remove the `mention` field from text parts when messaging a direct chat
2024	Recipient asked you to stop messaging them	403	Stop sending to this recipient — continuing to message someone who asked you to stop puts your line’s ability to deliver at risk
2025	Blocked handle not found	404	List your blocked handles via `GET /v3/blocked_handles` — the handle must match the stored, normalized form exactly
2026	Recipient is blocked	403	List your blocked handles via `GET /v3/blocked_handles` and unblock the recipient with `DELETE /v3/blocked_handles` to send to them again
2027	The sender phone number is currently restricted from sending due to its line reputation	403	Retry from a different phone number on your account
2028	App Clip payment cards can only be sent over iMessage	409	Omit `preferred_service` — it defaults to iMessage for App Clip cards — or set it to `iMessage`

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 the request after 1-5 seconds
3002	Server operation failed	500	Retry the request after 1-5 seconds
3003	Service connection error	500	Retry the request after 1-5 seconds
3004	Service operation failed	500	Retry the request after 1-5 seconds
3005	Network timeout	504	Retry the request after a short delay
3006	Internal server error	500	If the error persists, contact support with the `trace_id` from the error response
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 the message again
4002	Phone not available	500	Check the status of the sender line in your dashboard — though the line can appear healthy while its messaging connection is unavailable.
4003	Webhook delivery failed	500	Ensure your endpoint is publicly reachable
4004	Service unavailable	503	Retry the request after 30 seconds
4005	Recipient does not support this message type	422	Confirm the recipient is iMessage-capable before sending app messages — see the iMessage capability check
4006	Message send timed out	500	Wait briefly for a `message.sent` or `message.delivered` webhook; if none arrives, retry with a new idempotency key (reusing the original key returns the stored failed message without sending)
4007	Messaging service reported a send failure	500	Retry the message; transient service-side failures are common
4008	Sender is not eligible to send this message	403	Check the sender line’s status in your dashboard
4009	Sender line has no RCS account	503	Send from a different line on your account, or send without `preferred_service` so delivery falls back to SMS.
4010	RCS capability check unavailable	503	Retry the request after 30 seconds.

5xxx — Attachment/File Errors

Code	Message	HTTP	Troubleshooting
5001	File upload failed	500	Retry the upload (or the message that contained the attachment)
5002	File download failed	500	Ensure the URL is publicly accessible
5003	Failed to generate file URL	500	Retry the request
5004	Invalid file type	400	Supported file types include JPEG, PNG, GIF, MP4, and PDF
5005	File too large	400	Reduce or compress the file before uploading
5006	Content type mismatch	400	Ensure the URL extension matches the actual file type
5007	Failed to download image from the provided URL	400	Ensure the URL is publicly accessible and returns a valid image