Error codes

Every PubNub API call returns an HTTP status code. A PubNub SDK doesn't hand you that code directly. It wraps the outcome in a status object and, for most operations, a descriptive status category such as PNAccessDeniedCategory. The code below is what's on the wire, not what your handler branches on.

This page catalogs the HTTP status codes themselves. For the category names your SDK uses, and how to branch on them in code, refer to Connection management and your SDK's status events reference, for example JavaScript.

The codes below apply to PubNub's REST APIs, which every SDK calls underneath its own interface. A Function attached to a channel can return other codes of its own, defined by whatever logic runs inside it.

Success codes

Code	Operation	Meaning
200	General	The request succeeded. The response body contains the requested data.
204	Files	The request succeeded with no content returned. This is normal for a file upload, since the file is already in storage by the time the response arrives.
207	Message Actions	The action was deleted, but the deletion event wasn't published to subscribers.

Client error codes

Code	Operation	Meaning	Where to go
400	General	The request was malformed or missing a required parameter.	Check the parameters against the operation's entry in your SDK's reference. Refer to Available SDKs to find it.
403	General	The key or token making the request doesn't have the permission the operation needs.	Access Manager describes the permission model. Check available permissions to decode a token and confirm what it actually grants. If the token expired, refer to Update an expired token. If it was revoked, refer to Revoke a token. SDKs surface this as PNAccessDeniedCategory.
408	General	The client didn't finish sending the request body within the allowed time.	Check for a slow or stalled request on your side, close the connection, and retry.
412	App Context	An update sent with ifMatchesEtag didn't match the record's current eTag, so PubNub rejected it instead of overwriting a change it hadn't seen.	Fetch the record again for its current eTag, then retry the update with that value. Refer to Manage user metadata or Manage channel metadata for the parameter this depends on.
413	General	The request body exceeds the size that endpoint accepts.	Reduce the request body. Refer to the endpoint's SDK reference and API limits for the applicable size limit.
414	General	The request URI exceeds the maximum request size.	Shorten the URI. If you're requesting many channels at once on a single call, reduce how many you request together. Refer to API limits for the size itself.
415	App Context	The request body isn't JSON.	Send the body as JSON.
429	General	The subscribe key sent more requests than its current rate allows.	Reduce request volume and retry. Refer to API limits for the ceiling itself, and to Rate limiting if the source is one channel with a very large audience. Contact PubNub Support if your keyset needs a higher rate.

Server error codes

Code	Operation	Meaning	Where to go
502	General	PubNub's gateway couldn't reach the upstream service after retrying.	Retry with backoff. If it persists, check PubNub Status for an active incident, then contact PubNub Support.
503	General	The server is temporarily overloaded or unreachable. On a channel with a Before Publish Function attached, PubNub rejects the request outright instead of forwarding it upstream. The Function never runs, and the publisher receives a 503 directly.	Retry with backoff. Check PubNub Status if it persists.
504	General	The upstream service or the authentication service didn't respond within the allowed time.	Retry with backoff. Contact PubNub Support if it persists.

When the code alone isn't the whole story

Some outcomes never produce an HTTP status at all, because the request never reached PubNub in the first place. A client-side timeout, a DNS failure, or a subscribe that never connected all surface as a status category with no code behind them, such as PNTimeoutCategory or PNConnectionErrorCategory. Connection management covers those categories, what causes each one, and what your application should do about it.

If a code or category you're seeing doesn't match anything on this page, refer to Troubleshooting to find out where to look next.

Next steps

• Troubleshooting. Find where to look when a code or category doesn't match anything on this page.
• Connection management. The status categories SDKs report instead of a raw HTTP code, and what each one means.
• Access Manager. The permission model behind every 403.
• API limits. The soft and hard limits behind 413, 414, and 429.
• Rate limiting. Keep a channel with a very large audience under its rate limit instead of hitting 429.
• Architectural choices. Where error handling fits into your application's design, rather than a patch you add after users report it.