---
source_url: https://www.pubnub.com/docs/general/resources/troubleshooting
title: Troubleshooting
updated_at: 2026-06-04T11:10:30.210Z
---

> Documentation Index
> For a curated overview of PubNub documentation, see: https://www.pubnub.com/docs/llms.txt
> For the full list of all documentation pages, see: https://www.pubnub.com/docs/llms-full.txt


# Troubleshooting

PubNub APIs return status codes for successful and unsuccessful operations. SDKs surface these codes, especially for errors. Handle errors in your client. Show a helpful message. Retry the operation when appropriate.

Refer to [SDK troubleshooting and status event references](#sdk-troubleshooting-and-status-event-references) below for links to SDK‑specific guidance.

## HTTP status codes

Each HTTP response includes a status code in the header:

* 2xx or 3xx for success
* 4xx or 5xx for failure

In addition to common codes (200 OK, 400 Bad Request, 404 Not Found), these less‑common codes may appear. Functions can return other codes; see your SDK’s reference for details.

### Success codes

| Code | Operation | Description |
| --- | --- | --- |
| `200` | General | Request succeeded. The response body contains the requested data. |
| `204` | Files | Request succeeded with no content returned. This is normal for file upload operations where the file was successfully uploaded to storage. The SDK treats this as a successful response. |
| `207` | Message Actions | The action was deleted but the action-deletion message wasn't published. |

### Client error codes

| Code | Operation | Description | How to resolve |
| --- | --- | --- | --- |
| `400` | General | Bad request. The request was malformed or missing required parameters. | Check the request parameters and format. |
| `403` | General | Not authorized. The authorization key doesn't have the required permissions. | Verify [Access Manager](https://www.pubnub.com/docs/general/security/access-control) permissions for the key. For REST API calls, check the [generated signature](https://www.pubnub.com/docs/sdks/rest-api/access-manager-introduction). In SDKs, this maps to `PNAccessDeniedCategory`. |
| `408` | General | Request timeout. The client didn't finish sending the request body within the allowed time window. | Check for slow or stalled request body sends in your client code. Close and reopen the connection, then retry. |
| `412` | App Context | Precondition failed. The conditional operation couldn't be performed because the target object has changed since the last retrieval. This occurs when using the `ifMatchesEtag` parameter for optimistic locking. | Fetch the latest version of the object, get the new ETag, and retry the update. See [Concurrent updates (412)](#concurrent-updates-412) below. |
| `413` | General | Request entity too large. The request body exceeds the allowed size limit for the API. | Reduce the request body size. Refer to [Limits](https://www.pubnub.com/docs/general/setup/limits) for more information. |
| `414` | General | URI too long. The request URI exceeds the maximum allowed length of 32 KiB. | Shorten the URI. If you are using channel multiplexing, reduce the number of channels per request. |
| `415` | App Context | Unsupported media type. The format of the request body you supplied isn't supported. | Ensure the request body is in JSON format. |
| `429` | General | Rate limit exceeded. The subscribe key has sent too many requests to this API within the allowed rate. | Reduce the number of requests and retry. Refer to [Limits](https://www.pubnub.com/docs/general/setup/limits) for more information. If you need a higher rate limit for your keyset, contact [PubNub Support](https://support.pubnub.com). |

### Server error codes

| Code | Operation | Description | How to resolve |
| --- | --- | --- | --- |
| `502` | General | Bad gateway. The PubNub gateway couldn't reach the upstream service after all retries. | Retry with exponential backoff. If the error persists, check [PubNub status](https://status.pubnub.com) and contact [PubNub Support](https://support.pubnub.com). |
| `503` | General | Service unavailable. The server is temporarily overloaded or unreachable. When this occurs on a channel with a Before Publish Function deployed, the request is rejected (not forwarded to the upstream) and the publisher receives a 503. Publishes resume once the Functions service recovers. | Retry with exponential backoff. If the error persists, check [PubNub status](https://status.pubnub.com) and contact [PubNub Support](https://support.pubnub.com). |
| `504` | General | Gateway timeout. The upstream service or authentication service didn't respond within the allowed time window. | Retry with exponential backoff. If the error persists, contact [PubNub Support](https://support.pubnub.com). |

## Concurrent updates (412)

When multiple clients or processes update the same App Context object (user metadata or channel metadata) simultaneously, you may encounter HTTP 412 (Precondition Failed) errors. This happens when using the `ifMatchesEtag` parameter for optimistic locking.

### How ETag works

1. When you fetch metadata, the response includes an `eTag` field containing a version identifier.
2. When updating metadata, you can pass this ETag value in the `ifMatchesEtag` parameter.
3. The server compares your ETag with the current version. If they don't match (meaning someone else updated the object), the server returns 412.

:::tip When to use ETag
Use `ifMatchesEtag` when you need to prevent lost updates in scenarios where multiple clients might modify the same object. If you don't need this level of consistency, you can omit the parameter and the update will always succeed (last write wins).
:::

## Unrecognized errors

PubNub SDKs use descriptive status categories (such as `PNAccessDeniedCategory` or `PNTimeoutCategory`) for errors. If you encounter an error code or message not documented on this page or in your SDK's status events reference, it may originate from your application code, the operating system's networking layer, or another component in your stack.

When reporting an issue to [PubNub Support](https://support.pubnub.com), include the full error message, SDK version, and the operation that triggered it.

## SDK troubleshooting and status event references

Use these links to find SDK‑specific troubleshooting and status event references.

* **Asyncio** [troubleshooting](https://www.pubnub.com/docs/sdks/asyncio/troubleshoot) and [status events](https://www.pubnub.com/docs/sdks/asyncio/status-events)
* **C-Core** [troubleshooting](https://www.pubnub.com/docs/sdks/c-core/troubleshoot) and [status events](https://www.pubnub.com/docs/sdks/c-core/status-events)
* **FreeRTOS** [troubleshooting](https://www.pubnub.com/docs/sdks/freertos/troubleshoot) and [status events](https://www.pubnub.com/docs/sdks/freertos/status-events)
* **Mbed** [troubleshooting](https://www.pubnub.com/docs/sdks/mbed/troubleshoot) and [status events](https://www.pubnub.com/docs/sdks/mbed/status-events)
* **Objective-C** [troubleshooting](https://www.pubnub.com/docs/sdks/objective-c/troubleshoot) and [status events](https://www.pubnub.com/docs/sdks/objective-c/status-events)
* **POSIX C** [troubleshooting](https://www.pubnub.com/docs/sdks/posix-c/troubleshoot) and [status events](https://www.pubnub.com/docs/sdks/posix-c/status-events)
* **POSIX C++** [troubleshooting](https://www.pubnub.com/docs/sdks/posix-cpp/troubleshoot) and [status events](https://www.pubnub.com/docs/sdks/posix-cpp/status-events)
* **Python** [troubleshooting](https://www.pubnub.com/docs/sdks/python/troubleshoot) and [status events](https://www.pubnub.com/docs/sdks/python/status-events)
* **Ruby** [troubleshooting](https://www.pubnub.com/docs/sdks/ruby/troubleshoot) and [status events](https://www.pubnub.com/docs/sdks/ruby/status-events)
* **Unity** [troubleshooting](https://www.pubnub.com/docs/sdks/unity/troubleshoot) and [status events](https://www.pubnub.com/docs/sdks/unity/status-events)
* **Windows C** [troubleshooting](https://www.pubnub.com/docs/sdks/windows-c/troubleshoot) and [status events](https://www.pubnub.com/docs/sdks/windows-c/status-events)
* **Windows C++** [troubleshooting](https://www.pubnub.com/docs/sdks/windows-cpp/troubleshoot) and [status events](https://www.pubnub.com/docs/sdks/windows-cpp/status-events)