Link Header Pagination — REST API Pagination Header Implementation Errors
About Link Header Pagination
Fix Link header pagination errors in REST APIs including malformed Link headers, missing rel values, and client parsing failures for paginated responses. This guide covers everything you need to know about this topic, including common causes, step-by-step solutions, and answers to frequently asked questions.
Here are the key things to understand: Link headers provide pagination URLs for REST APIs following RFC 8288 (Web Linking). Standard rel values are: first, prev, next, last — indicating pagination directions. GitHub API popularized this pattern: Link: <url>; rel="next", <url>; rel="last". Link headers keep pagination metadata in headers rather than the response body. Parsing Link headers requires handling URL encoding, quoted strings, and multiple values. Understanding these fundamentals will help you diagnose and resolve this issue more effectively.
The most common reasons this occurs include: Link header format not following RFC 8288 — missing angle brackets around URLs or quotes around rel values. URL parameters in Link header not properly encoded (& characters in URLs). Client not parsing Link headers and instead hard-coding pagination logic. Server not including Link headers for the last page, confusing client pagination logic. Identifying the root cause is the first step toward finding the right solution.
To resolve this, follow these recommended steps: Format Link headers correctly: Link: <https://api.example.com/items?page=2>; rel="next", <https://api.example.com/items?page=5>; rel="last". URL-encode any special characters in the Link header URLs. Include all four rel values (first, prev, next, last) where applicable — omit prev on page 1 and next on the last page. Use a Link header parsing library in your client (parse-link-header for Node.js, or regex for simple cases). Also include pagination metadata in the response body (total_count, page, per_page) for convenience. If these steps do not resolve the issue, consider consulting additional resources or a qualified professional.
This article is part of our HTTP Status Codes collection on Error Codes Wiki. We provide comprehensive, up-to-date information to help you find solutions quickly.
Quick Answer
Why use Link headers instead of body pagination?
Link headers separate pagination metadata from resource data, following HATEOAS principles. The client does not need to know the URL structure — it just follows the provided links.
Overview
Fix Link header pagination errors in REST APIs including malformed Link headers, missing rel values, and client parsing failures for paginated responses.
Key Details
- Link headers provide pagination URLs for REST APIs following RFC 8288 (Web Linking)
- Standard rel values are: first, prev, next, last — indicating pagination directions
- GitHub API popularized this pattern: Link: <url>; rel="next", <url>; rel="last"
- Link headers keep pagination metadata in headers rather than the response body
- Parsing Link headers requires handling URL encoding, quoted strings, and multiple values
Common Causes
- Link header format not following RFC 8288 — missing angle brackets around URLs or quotes around rel values
- URL parameters in Link header not properly encoded (& characters in URLs)
- Client not parsing Link headers and instead hard-coding pagination logic
- Server not including Link headers for the last page, confusing client pagination logic
Steps
- 1Format Link headers correctly: Link: <https://api.example.com/items?page=2>; rel="next", <https://api.example.com/items?page=5>; rel="last"
- 2URL-encode any special characters in the Link header URLs
- 3Include all four rel values (first, prev, next, last) where applicable — omit prev on page 1 and next on the last page
- 4Use a Link header parsing library in your client (parse-link-header for Node.js, or regex for simple cases)
- 5Also include pagination metadata in the response body (total_count, page, per_page) for convenience