Rate limits and error codes
The 60 requests a minute API limit, the JSON error envelope and every status and error_code the Shakewell Wallet public API returns, with fixes.
Last updated 2026-11-05
Rate limits
| Scope | Limit | On excess |
|---|---|---|
Public API (all /api/public/v1 routes) | 60 requests per minute, counted per IP address | 429, body error_code: "HTTP_ERROR" |
| Hosted signup registration | 10 requests per minute per IP address and route | 429 with retry_after in the body |
Limits are per IP address, not per key, so servers sharing an address share the budget. On a 429, wait at least a minute before retrying, then spread bulk work over time or use the template-wide bulk notification.
Error envelope
Errors raised by the API use one JSON shape. error_code is stable, so branch on it rather than on message.
{
"error": true,
"error_code": "WALLET_PASS_NOT_FOUND",
"message": "Wallet pass not found.",
"timestamp": "2026-11-05T01:23:45.000000Z"
}Two older shapes still appear: authentication failures return { "error": "Unauthorized", "message": "..." }, and template endpoints return { "success": false, "message": "..." } for some failures.
Status and code reference
| Status | Code or error | Where | Fix |
|---|---|---|---|
| 400 | PASS_NOT_INSTALLED | push to one pass | Wait until the customer has added the pass |
| 401 | Unauthorized | any route | Send a valid key |
| 403 | feature_required | creating keys | Move to a plan with API access |
| 403 | template_limit_exceeded | create template | Delete a template or upgrade |
| 403 | UNAUTHORIZED_ACCESS | update or delete template | Use a write key for your own template |
| 403 | ACCOUNT_CONTEXT_MISSING | templates | Contact support |
| 404 | WALLET_PASS_NOT_FOUND | passes, push | Check the ID and the account |
| 404 | RESOURCE_NOT_FOUND | any | Check the resource ID |
| 409 | WALLET_PASS_TEMPLATE_MISSING | update pass | Re-create the pass on a live template |
| 422 | VALIDATION_ERROR | any write | Read errors for field names |
| 429 | HTTP_ERROR, Too Many Attempts. | any | Wait a minute, then retry |
| 500 | WALLET_PASS_CREATE_FAILED, WALLET_PASS_UPDATE_FAILED, WALLET_PASS_DELETE_FAILED, WALLET_PASS_RETRIEVE_FAILED, WALLET_PASS_LIST_FAILED | passes | Retry with backoff, then contact support |
| 500 | NOTIFICATION_SEND_FAILED, BULK_NOTIFICATION_SEND_FAILED | push | Retry with backoff |
| 500 | INTERNAL_ERROR | any | Retry, then contact support |
Each of the common ones has its own troubleshooting page.