generated: '2026-08-13' method: searched source: >- https://developers.line.biz/en/reference/messaging-api/ (Common specifications) and https://developers.line.biz/en/docs/messaging-api/retrying-api-request/, cross-checked against openapi/line-messaging-api-openapi.yml description: >- Cross-cutting runtime semantics for the LINE Messaging API and the sibling LINE platform APIs: how a caller authenticates, how it retries safely, how it pages, how it traces a request, and what an error looks like on the wire. authentication: style: bearer-token header: "Authorization: Bearer {CHANNEL_ACCESS_TOKEN}" scheme_name: Bearer granularity: per-channel description: >- Every Messaging API, Insight, Manage Audience, LIFF, Module and Shop call carries a channel access token as an HTTP Bearer credential. Tokens are scoped to a single LINE channel, not to a user or an account, so rate limits and message quotas are also counted per channel. Four token flavours exist — long-lived, short-lived (v2.0), JWT-assertion (v2.1) and stateless (v3) — all issued by the Channel Access Token API. The module-attach endpoint on manager.line.biz is the one exception: it uses HTTP Basic. see: authentication/line-authentication.yml oauth: surface: LINE Login v2.1 (end-user authorization, separate from channel tokens) discovery: https://access.line.me/.well-known/openid-configuration pkce: S256 (only method supported) see: scopes/line-scopes.yml idempotency: supported: true header: X-Line-Retry-Key value_format: hexadecimal UUID generated by the caller generated_by: client retention: 24 hours from the first request scope: >- Per channel and per API request. The retry key must be sent on the FIRST request — a request made without X-Line-Retry-Key can never be retried safely. conflict_status: 409 conflict_body: '{"message": "The retry key is already accepted"}' conflict_header: >- x-line-accepted-request-id — carries the x-line-request-id of the request that was originally accepted, so the caller can correlate. For push messages the 409 body also repeats the original sentMessages[].id and sentMessages[].quoteToken. supported_operations: - pushMessage - multicast - narrowcast - broadcast rejected_elsewhere: >- Sending X-Line-Retry-Key to any operation outside that list is rejected with 400. retry_guidance: retry_on: [500, timeout] do_not_retry_on: [2xx, 409, other 4xx] backoff: >- Exponential backoff is recommended. A retried request still consumes rate limit, so frequent retries can trigger 429. caveat: >- The retry key prevents duplicate execution; it does not guarantee delivery. Once the platform accepts a request (200) it cannot be retried even if the message was never delivered — for example because the user blocked the Official Account. docs: https://developers.line.biz/en/docs/messaging-api/retrying-api-request/ pagination: style: continuation-token request_params: - name: start in: query description: >- Continuation token returned as `next` in the previous response. Omit on the first call. - name: limit in: query description: Maximum number of items to return in one response. response_fields: - name: next description: >- Present only when more items remain; pass it back as `start`. Absent means the walk is complete. applies_to: - getFollowers - getGroupMembersIds - getRoomMembersIds - getRichMenuAliasList - getAudienceGroups - getJoinedMembershipUsers - listCoupon note: >- Manage Audience list endpoints additionally use page/size query parameters with a totalCount response field rather than a continuation token — the two styles coexist across the platform. request_tracing: response_header: X-Line-Request-Id description: >- Every Messaging API response carries X-Line-Request-Id, a unique ID issued per request. It is the identifier LINE support asks for, and it is also the join key against the delivery-statistics endpoints. When a retry key collides, X-Line-Accepted-Request-Id names the earlier request that won. secondary_headers: - name: X-Line-Accepted-Request-Id when: 409 on a retry-key conflict - name: X-Line-Delivery-Tag when: >- Request header on partner LINE notification message sends; echoed back in the delivery webhook event. webhook_verification: header: x-line-signature algorithm: HMAC-SHA256 over the raw request body, keyed with the channel secret, Base64-encoded note: >- Signature must be computed over the raw bytes, before any JSON parsing or re-serialization. See asyncapi/line-messaging-webhook.yml. docs: https://developers.line.biz/en/docs/messaging-api/verify-webhook-signature/ versioning: style: uri-path current: v2 examples: - /v2/bot/... — Messaging API, Insight, Manage Audience, Module - /oauth2/v2.1/... — Channel Access Token (JWT assertion) and LINE Login - /oauth2/v3/token — stateless channel access token - /liff/v1/apps — LIFF server API - /shop/v3/mission — Mission Sticker API note: >- Path version segments are per-API, not platform-wide: v1, v2, v2.1 and v3 are all live simultaneously on api.line.me. LIFF (the client SDK) is the only surface on semantic versioning. see: lifecycle/line-lifecycle.yml error_envelope: format: proprietary JSON rfc9457: false content_type: application/json shape: message: String — human-readable summary of the error. details: Array — present only when non-empty. details[].message: String — detail of the individual error. details[].property: >- String — JSON field name or query parameter where the error occurred. example: | { "message": "The request body has 2 error(s)", "details": [ {"message": "May not be empty", "property": "messages[0].text"}, {"message": "Must be one of the following values: [text, image, video, audio, location, sticker, template, imagemap]", "property": "messages[1].type"} ] } note: >- There is no machine-readable error `code` field — callers must match on the `message` string, which is documented as a fixed catalogue but is not typed. see: errors/line-problem-types.yml rate_limit_signalling: exhaustion_status: 429 response_headers: none algorithm: token bucket (documented, refill rate not published) note: >- LINE publishes per-endpoint limits in the reference but returns NO RateLimit-* or X-RateLimit-* response headers and no Retry-After. A caller cannot read remaining budget at runtime; it can only observe the 429. The only quota an API call can read is the monthly message allowance, via getMessageQuota and getMessageQuotaConsumption. see: rate-limits/line-rate-limits.yml payload_limits: max_request_size: 2MB (413 Payload Too Large above this) url_encoding: >- Domain names, paths, query parameters and fragments inside request-body properties must be percent-encoded as UTF-8. content_hosts: api.line.me: All API endpoints except the binary ones below. api-data.line.me: >- getMessageContent, getMessageContentPreview, setRichMenuImage, getRichMenuImage, createAudienceForUploadingUserIds (by file), addUserIdsToAudience (by file). Using the wrong host is a common integration failure — the two hosts are not interchangeable. manager.line.biz: attachModule (Module Attach API), HTTP Basic auth. access.line.me: LINE Login authorization endpoint and OIDC discovery. validation_endpoints: supported: true description: >- LINE publishes dry-run validators for message objects and rich menus, so a caller can check a payload without spending message quota. operations: - validateReply - validatePush - validateMulticast - validateNarrowcast - validateBroadcast - validateRichMenuObject - validateRichMenuBatchRequest see: sandbox/line-sandbox.yml