Errors
Errors use standard HTTP status codes and one JSON shape. doc links to the code’s section on this page, so an agent can look it up.
{"error":{"code":"missing_field","message":"`to` or `device` is required","param":"to","doc":"https://pushfleet.com/docs/api/errors#missing_field"}}param names the field at fault when there is one. 5xx errors are on PushFleet’s side and safe to retry with the same idempotency key.
invalid_request
Section titled “invalid_request”400. The body isn’t valid JSON, or the request is malformed in a way no single field explains.
missing_field
Section titled “missing_field”400. A required field is missing. param names it.
invalid_field
Section titled “invalid_field”400. A field has the wrong type or an unsupported value, such as a priority other than normal or high.
invalid_key
Section titled “invalid_key”401. The key is missing, malformed, revoked or unknown.
missing_scope
Section titled “missing_scope”403. The restricted key doesn’t have the scope this request needs. message names the scope.
user_token_required
Section titled “user_token_required”403. A device registration in live mode with a publishable key didn’t include a valid userToken. See identity verification.
not_found
Section titled “not_found”404. The message, device, template or key doesn’t exist in this environment.
unknown_user
Section titled “unknown_user”404. The user has no registered devices in this environment, so there’s nothing to send to.
idempotency_conflict
Section titled “idempotency_conflict”409. The Idempotency-Key was already used in the last 24 hours with a different request body.
payload_too_large
Section titled “payload_too_large”413. The notification would be bigger than 4 KB once built for Apple or Google.
rate_limited
Section titled “rate_limited”429. Too many requests for this key. Wait for Retry-After seconds. See rate limits.
internal_error
Section titled “internal_error”500. Something failed on PushFleet’s side. Retry with the same idempotency key.