On this page

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 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​

CodeOperationDescription
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​

CodeOperationDescriptionHow 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 permissions for the key. For REST API calls, check the generated signature. In SDKs, this maps to PNAccessDeniedCategory.
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) below.
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.

Server error codes​

CodeOperationDescriptionHow to resolve
503
General
Service unavailable. Request timed out or the server is temporarily overloaded.
Retry with exponential backoff. If the error persists, contact PubNub Support.

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.
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, 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.

Last updated on
On this page