Error Codes

Overview

Complete reference of Apple Messages error codes with troubleshooting guides.

Every error returns the same JSON envelope: a success: false flag, a nested error object, and a request_id naming the request that failed. The error object carries a numeric code and a doc_url pointing at that code’s page here.

{
  "success": false,
  "error": {
    "status": 404,
    "code": 2001,
    "message": "Chat not found",
    "doc_url": "https://docs.linqapp.com/channel/amb/error/codes/2xxx/2001/"
  },
  "request_id": "req_01JQZ8X4K2N3P5R7T9V1W3Y5Z7"
}

error.code is a number and is the field to branch on. error.message is written for a human reading a log and may be reworded at any time, so matching on it will break.

Three fields appear only when they apply: param names the field a validation error is about, retry_after gives the seconds to wait, and details carries an array of field-level conditions. trace_id appears when tracing is enabled.

These codes belong to Apple Messages. Every channel numbers its own errors, which is why the doc_url is namespaced to /channel/amb/ — the same integer means something different on another channel, so branch on the code only in code paths you know are talking to this API.

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

When retry_after is present, it overrides the guidance above: wait that many seconds, then retry.

1xxx — Client/Request Errors

The request never reached the thing it was about. Fix the request and send it again; retrying it unchanged fails identically.

Code	Message	HTTP	Troubleshooting
1001	Missing required field	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1002	Backlog horizon exceeded	429	Wait the number of seconds in the `Retry-After` header (and `retry_after` in the body), then retry the same request unchanged.
1003	Invalid request body	400	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1004	Batch exceeds horizon	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1005	Batch invalid	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1006	a JSON body is required; `{}` to change nothing	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1007	Rate limit exceeded	429	Wait the number of seconds in the `Retry-After` header (and `retry_after` in the body), then retry the same request unchanged.
1008	Business hours invalid	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1009	Business id invalid	400	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1010	Category invalid	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1011	Channel unsupported	400	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1012	Count out of range	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1013	resume token is not one this API issued; reconnect without Last-Event-ID (and re-list	400	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1014	Description too long	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1015	Duplicate	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1016	Duplicate id	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1017	attachment body is empty	400	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1018	Enabled events duplicate	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1019	Enabled events required	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1020	Enabled events unknown	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1021	Escalation handling invalid	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1022	Expiry invalid	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1023	Field mismatch	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1024	Field removed	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1025	the body carries trailing content after the definition	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1026	Flow reserved	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1027	Forbidden character	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1028	Forbidden identifier	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1029	Forbidden policy phrase	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1030	hours_timezone must be an IANA zone name this platform can load, e.g. America/New_York	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1031	Idempotency-Key header is required on all sends; it makes blind retries safe	400	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1032	If match invalid	400	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1033	If match required	428	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1034	Integration invalid	400	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1035	Invalid	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1036	Invalid timestamp	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1037	Invalid type	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1038	Invalid url	400	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1039	the body must be multipart/form-data with a `name` field and an optional `logo` file part	400	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1040	name is required; it is the brand name printed on the invitation card	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1041	Non bmp character	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1042	Not before too far	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1043	Not future	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1044	Not single line	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1045	Not whole minute	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1046	On invalid invalid	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1047	Operator invalid	400	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1048	Out of range	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1049	Overlap hours invalid	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1050	Param invalid	400	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1051	Part invalid	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1052	Parts empty	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1053	Parts invalid	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1054	Replay max out of range	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1055	until is before since, so the range names no events	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1056	Replay range too large	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1057	Replay selector conflict	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1058	Replay selector required	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1059	Replay too many ids	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1060	no flow named	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1061	Secret value required	400	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1062	Server owned	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1063	since must be an RFC3339 timestamp, e.g. 2026-08-14T00:00:00Z	400	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1064	Source invalid	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1065	Spread over seconds invalid	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1066	State invalid	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1067	Subject invalid	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1068	Subject kind invalid	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1069	subject is required	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1070	template_id is required: a batch sends one of your invitation templates to every recipient	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1071	To invalid	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1072	To required	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1073	flow definition exceeds the size ceiling	413	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1074	Too long	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1075	Too many messages	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1076	Unhandled form kind	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1077	Unknown app extension	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1078	Unknown page	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1079	Unknown parameter	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1080	Unknown part type	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1081	Unknown template	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1082	Url invalid	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1090	Claim required	400	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1091	Degrade invalid	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1092	Duplicate recipient	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1093	No valid recipients	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1094	recipients must carry at least one row	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1095	Too many recipients	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1096	Typing lead invalid	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1097	File conflicting	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1098	File part misplaced	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1099	File part missing	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1100	File part unused	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1101	Image att id reserved	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1102	Logo conflicting	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.
1103	Unknown image id	422	Check this endpoint’s request schema in the API reference; `param` in the response names the exact field at fault.

2xxx — Resource Errors

The request was well formed and the thing it named was missing, not yours, or not in a state that allows this.

An id that belongs to another brand answers exactly like one that does not exist. That is deliberate: it keeps one brand from probing another’s ids.

Code	Message	HTTP	Troubleshooting
2001	Chat not found	404	Verify the id came from a previous response on this brand’s credential.
2002	Message not found	404	Verify the id came from a previous response on this brand’s credential.
2003	Attachment not found	422	Verify the id came from a previous response on this brand’s credential.
2005	App extension not configured	409	Verify the id came from a previous response on this brand’s credential.
2006	Apple pay not configured	409	Verify the id came from a previous response on this brand’s credential.
2007	Attachment not ready	409	Verify the id came from a previous response on this brand’s credential.
2008	your brand already holds a different business id on channel	409	Verify the id came from a previous response on this brand’s credential.
2009	Chat already claimed	409	Verify the id came from a previous response on this brand’s credential.
2010	the chat is closed	409	Verify the id came from a previous response on this brand’s credential.
2011	a flow can only start while the partner owns the chat	409	Verify the id came from a previous response on this brand’s credential.
2012	Chat superseded	409	Verify the id came from a previous response on this brand’s credential.
2013	Claim invalid	403	Verify the id came from a previous response on this brand’s credential.
2014	this brand does not attest its own consent (its consent_mode is linq_managed)	409	Verify the id came from a previous response on this brand’s credential.
2015	no valid opt-in on file for this notification category	403	Verify the id came from a previous response on this brand’s credential.
2016	Cross brand conflict	409	Verify the id came from a previous response on this brand’s credential.
2017	Endpoint limit reached	409	Verify the id came from a previous response on this brand’s credential.
2018	this brand already has an endpoint at that URL. If you are retrying a create whose	409	Verify the id came from a previous response on this brand’s credential.
2019	we are holding this brand on managed escalation; contact support to release the lock	409	Verify the id came from a previous response on this brand’s credential.
2020	no such event	404	Verify the id came from a previous response on this brand’s credential.
2021	no flow with that id	404	Verify the id came from a previous response on this brand’s credential.
2022	no such flow or chat	404	Verify the id came from a previous response on this brand’s credential.
2023	the original request with this key is still processing; retry shortly	409	Verify the id came from a previous response on this brand’s credential.
2024	this Idempotency-Key was used with a different request body	409	Verify the id came from a previous response on this brand’s credential.
2025	that ownership change isn’t valid from the chat’s current owner	409	Verify the id came from a previous response on this brand’s credential.
2026	Integration group not found	404	Verify the id came from a previous response on this brand’s credential.
2027	this request carries no resolved API key	401	Verify the id came from a previous response on this brand’s credential.
2028	invitation batch not found	404	Verify the id came from a previous response on this brand’s credential.
2029	Invitation card not granted	403	Verify the id came from a previous response on this brand’s credential.
2030	Invitation chat not addressable	409	Verify the id came from a previous response on this brand’s credential.
2031	Invitation not found	404	Verify the id came from a previous response on this brand’s credential.
2032	Invitation template not authorized	403	Verify the id came from a previous response on this brand’s credential.
2033	no invitation template with that id	404	Verify the id came from a previous response on this brand’s credential.
2034	message template not found	404	Verify the id came from a previous response on this brand’s credential.
2035	provide Authorization: Bearer sk_dev_…	401	Verify the id came from a previous response on this brand’s credential.
2036	Oauth not configured	409	Verify the id came from a previous response on this brand’s credential.
2037	unknown part type	404	Verify the id came from a previous response on this brand’s credential.
2038	a signing-key rotation is already in flight for this endpoint. The previous secret	409	Verify the id came from a previous response on this brand’s credential.
2039	Structure unsupported	409	Verify the id came from a previous response on this brand’s credential.
2040	Version conflict	412	Verify the id came from a previous response on this brand’s credential.
2041	Webhook endpoint not found	404	Verify the id came from a previous response on this brand’s credential.
2042	Webhook endpoint not receiving	409	Verify the id came from a previous response on this brand’s credential.
2052	Degrade requires sequence	409	Verify the id came from a previous response on this brand’s credential.
2053	Attachment failed	422	Verify the id came from a previous response on this brand’s credential.
2054	Attachment not sendable	422	Verify the id came from a previous response on this brand’s credential.
2056	this invitation template has no logo	404	Verify the id came from a previous response on this brand’s credential.
2057	Operator forbidden	403	Verify the id came from a previous response on this brand’s credential.

3xxx — Server Errors

Transient, and ours. Retry with exponential backoff, starting at 1 second and capping at 30. Sends are idempotent on Idempotency-Key, so a retry of a send that actually succeeded returns the original result rather than sending twice.

Code	Message	HTTP	Troubleshooting
3001	brand has no outbound channel account; cannot send as this brand	503	Retry with exponential backoff: this is our failure, not your request’s.
3002	AMB credentials not configured	503	Retry with exponential backoff: this is our failure, not your request’s.
3003	the server could not encode this frame	500	Retry with exponential backoff: this is our failure, not your request’s.
3004	the typing indicator could not be handed to the messaging channel; retry	502	Retry with exponential backoff: this is our failure, not your request’s.
3005	Streaming unsupported	500	Retry with exponential backoff: this is our failure, not your request’s.
3006	Internal server error	500	Retry with exponential backoff: this is our failure, not your request’s.

4xxx — Delivery Errors

What the send attempt discovered, or an operational refusal. Apple Messages has no delivery or read receipts — sent means Apple accepted the message — so this range is small by construction, and a code here is something we learned while handing the message over, not afterwards.

Code	Message	HTTP	Troubleshooting
4001	Capability unknown	409	This is an operational or capability refusal, not a malformed request; the same call may succeed later.
4002	this customer asked for the automated messages to stop; only the human desk may send here	403	This is an operational or capability refusal, not a malformed request; the same call may succeed later.
4003	sending is temporarily paused: the kill-switch state is not yet loaded; retry shortly	503	This is an operational or capability refusal, not a malformed request; the same call may succeed later.
4005	Capability unsupported	409	This is an operational or capability refusal, not a malformed request; the same call may succeed later.

5xxx — Attachment/File Errors

The file’s bytes: its format, its size, where it came from, or storing it. An attachment that is merely missing or not yet readable is a 2xxx resource error instead.

Code	Message	HTTP	Troubleshooting
5001	attachment source capacity is busy; retry shortly	503	Wait the number of seconds in the `Retry-After` header (and `retry_after` in the body), then retry the same request unchanged.
5002	attachment source returned an empty body	422	Check the file against the documented size and format limits for this field.
5003	attachment source was refused by the secure URL policy	422	Check the file against the documented size and format limits for this field.
5004	attachment source bytes exceed the 100 MB request limit	413	Check the file against the documented size and format limits for this field.
5005	attachment source fetching is temporarily unavailable	502	Check the file against the documented size and format limits for this field.
5006	attachment storage is unavailable for this brand right now;	503	Wait the number of seconds in the `Retry-After` header (and `retry_after` in the body), then retry the same request unchanged.
5007	the logo must be a real PNG (checked by signature, not filename or content-type)	422	Check the file against the documented size and format limits for this field.
5008	Bubble image aspect	422	Check the file against the documented size and format limits for this field.
5009	Interactive image format unsupported	422	Check the file against the documented size and format limits for this field.
5010	Interactive image too large	413	Check the file against the documented size and format limits for this field.
5011	Interactive images too large	413	Check the file against the documented size and format limits for this field.
5012	Logo too large	422	Check the file against the documented size and format limits for this field.
5013	the default card image must be a PNG	422	Check the file against the documented size and format limits for this field.
5014	the default card image is over the 200 KB decoded cap for a preview card	413	Check the file against the documented size and format limits for this field.