Errors & Troubleshooting
HTTP status codes, error responses, and solutions for the PaperStack API.
| Code | Meaning | Cause |
|---|
200 | OK | Request succeeded |
302 | Redirect | Root endpoint redirects to API reference |
400 | Bad Request | Invalid year format, filename, or malformed URL |
401 | Unauthorized | Missing or malformed Authorization header |
403 | Forbidden | Invalid, expired, or revoked API key; no remaining credits |
404 | Not Found | Exam, year, shift, file, or diagram does not exist |
429 | Too Many Requests | Rate limit exceeded (check your plan's limit) |
500 | Internal Server Error | Gateway misconfiguration |
502 | Bad Gateway | Authentication service (Unkey) or data origin temporarily unavailable |
All errors return JSON with a single field:
{
"error": "Human-readable error description"
}
| Error Message | Cause | Solution |
|---|
Invalid year format. | Year parameter is not a 4-digit number | Use a valid year like 2024 |
Invalid filename. | File name doesn't match expected pattern | Use paper.json, physics.json, etc. |
| Error Message | Cause | Solution |
|---|
Missing API key. Include it as: Authorization: Bearer ps_xxxx | No Authorization header present | Add Authorization: Bearer <your_key> to all data requests |
Malformed Authorization header. Expected: Bearer ps_xxxx | Header doesn't match Bearer <key> format | Check your header format: Authorization: Bearer ps_xxxx |
| Error Message | Cause | Solution |
|---|
Invalid or expired API key. | Key doesn't exist, revoked, or expired | Create a new key in your dashboard |
API key has no remaining credits. | Key's credit balance is zero | Refill the key or create a new one |
| Error Message | Cause | Solution |
|---|
Not found. Use: /{exam}/{year}/{shift}/{file} | URL path has fewer than 4 segments | Follow the pattern: /neet/2024/s1/physics.json |
Shift "xxx" not found for neet/2024. | Shift identifier doesn't match any available shift | List available shifts via GET /neet/2024 |
File not found. Check year, shift, and filename. | The specific file doesn't exist | Verify the filename (paper.json, physics.json, etc.) |
| Error Message | Cause | Solution |
|---|
Rate limit exceeded. Max 2 req/s. | You've exceeded your plan's rate limit | Wait at least one second before retrying |
| Error Message | Cause | Solution |
|---|
Internal server error. | Unexpected gateway error | Retry the request; contact support if persistent |
Gateway misconfigured: UNKEY_API_ID is not set. | Server configuration issue | Contact PaperStack support |
Gateway misconfigured: CDN_BACKEND_URL is not set. | Server configuration issue | Contact PaperStack support |
| Error Message | Cause | Solution |
|---|
Auth error (HTTP xxx): ... | Authentication service (Unkey) returned an error | Retry; check status page for outages |
Auth unreachable: ... | Authentication service is unreachable | Retry; check status page for outages |
- Test with curl first — isolate your integration from application logic
- Check the status page — paperstack.instatus.com shows real-time API health
- Verify your API key — ensure it hasn't expired or been revoked in your dashboard
- Check URL format — paths are case-sensitive; use lowercase for exams and shift identifiers
- Monitor usage — your dashboard shows request volume and error rates
- Enable verbose logging — log
status and error fields for every API response during development