--- source_url: https://www.pubnub.com/docs/design-patterns/error-codes title: Error codes updated_at: 2026-09-30T07:20:08.000Z --- # Error codes ## Documentation index To discover more PubNub resources: 1. Fetch [PubNub's llms.txt](https://www.pubnub.com/llms-full.txt) for a list of available pages in Markdown format. 2. Identify relevant URLs from that index. 3. Fetch the target pages. Do not assume a path exists, always check the index first. 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](https://www.pubnub.com/docs/architecture/connection-management/overview.md#the-status-listener) and your SDK's status events reference, for example [JavaScript](https://www.pubnub.com/docs/sdks/javascript/status-events.md). The codes below apply to PubNub's REST APIs, which every SDK calls underneath its own interface. A [Function](https://www.pubnub.com/docs/message-processing/serverless/overview.md) 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](https://www.pubnub.com/docs/data-storage/files/overview.md) | 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](https://www.pubnub.com/docs/pub-sub/message-actions/overview.md) | 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](https://www.pubnub.com/docs/getting-started/available-sdks.md) to find it. | | `403` | General | The key or token making the request doesn't have the permission the operation needs. | [Access Manager](https://www.pubnub.com/docs/security/access-control/overview.md) describes the permission model. [Check available permissions](https://www.pubnub.com/docs/security/access-control/check-permissions.md) to decode a token and confirm what it actually grants. If the token expired, refer to [Update an expired token](https://www.pubnub.com/docs/security/access-control/update-expired-token.md). If it was revoked, refer to [Revoke a token](https://www.pubnub.com/docs/security/access-control/manage-permissions.md#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](https://www.pubnub.com/docs/data-storage/metadata/overview.md) | 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](https://www.pubnub.com/docs/data-storage/metadata/manage-user-metadata.md#set-user-metadata) or [Manage channel metadata](https://www.pubnub.com/docs/data-storage/metadata/manage-channel-metadata.md#set-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](https://www.pubnub.com/docs/architecture/limits.md) 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](https://www.pubnub.com/docs/architecture/limits.md#publish) for the size itself. | | `415` | [App Context](https://www.pubnub.com/docs/data-storage/metadata/overview.md) | 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](https://www.pubnub.com/docs/architecture/limits.md) for the ceiling itself, and to [Rate limiting](https://www.pubnub.com/docs/design-patterns/rate-limiting.md) if the source is one channel with a very large audience. Contact [PubNub Support](https://support.pubnub.com/hc/en-us) 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](https://status.pubnub.com) for an active incident, then contact [PubNub Support](https://support.pubnub.com/hc/en-us). | | `503` | General | The server is temporarily overloaded or unreachable. On a channel with a [Before Publish Function](https://www.pubnub.com/docs/message-processing/serverless/overview.md) 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](https://status.pubnub.com) 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](https://support.pubnub.com/hc/en-us) 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](https://www.pubnub.com/docs/architecture/connection-management/overview.md#the-status-listener) 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](https://www.pubnub.com/docs/design-patterns/troubleshooting.md) to find out where to look next. ## Next steps * [Troubleshooting](https://www.pubnub.com/docs/design-patterns/troubleshooting.md). Find where to look when a code or category doesn't match anything on this page. * [Connection management](https://www.pubnub.com/docs/architecture/connection-management/overview.md). The status categories SDKs report instead of a raw HTTP code, and what each one means. * [Access Manager](https://www.pubnub.com/docs/security/access-control/overview.md). The permission model behind every `403`. * [API limits](https://www.pubnub.com/docs/architecture/limits.md). The soft and hard limits behind `413`, `414`, and `429`. * [Rate limiting](https://www.pubnub.com/docs/design-patterns/rate-limiting.md). Keep a channel with a very large audience under its rate limit instead of hitting `429`. * [Architectural choices](https://www.pubnub.com/docs/design-patterns/architectural-choices.md#design-for-limits-and-failure-not-around-them). Where error handling fits into your application's design, rather than a patch you add after users report it. Last updated at: 2026-09-30T07:20:08.000Z