Troubleshoot payload unwrapping

This page shows you how to resolve issues with payload unwrapping.

HTTP status code errors

When using payload unwrapping, common HTTP status code errors can occur. You can monitor the errors with the push_request_count metric.

400 bad request

The following error occurs when Pub/Sub can't process the request due to a misconfiguration or missing data. 

400 Bad Request

This error occurs due to several reasons. The following are some of the most common causes of the error:

  • The payload (message data) doesn't match the expected request format specified by the HTTP endpoint.
  • The necessary headers to process the request are missing.
  • An incorrect HTTP endpoint is configured for the subscription.

To resolve this issue, try the following solutions:

  • Check the format of your payload (message data). Make sure it matches the expected request format specified by the HTTP endpoint.
  • Check that the request contains the required headers. If the headers are missing, you might need to add them in the message attributes. An example may include Content-Type, but others may be necessary as well.
  • Confirm that the HTTP endpoint configured for your subscription is valid.
  • Enable Dead Letter Queue (DLQ) on your push subscription. This redirects individual messages that can't be delivered. It's helpful to enable DLQ if you see a small number of 400 errors that you want to inspect.

401 unauthorized / 403 forbidden

The following error occurs when Pub/Sub can't process the request due to incorrect or invalid credentials.

401 unauthorized / 403 forbidden

This error occurs because the push subscription isn't authenticated.

To resolve this issue, try the following solutions:

  • Enable Push authentication. Using Push authentication is important if you are integrating with Cloud Run or App Engine.

    If push authentication doesn't work with your solution, then you might need to add your own authorization key or API key in the publish message attributes.

415 Unsupported Media Type

The following error occurs when Pub/Sub can't process the request because the payload format is in an unsupported format.

415 Unsupported Media Type

This error occurs due to several reasons. The following are some of the most common causes of the error:

  • The endpoint is missing the required media-type header.

To resolve this issue, try the following solution:

  • Your endpoint likely requires a Content-Type header. By default, payload unwrapping, doesn't set a media type header. You can set a Content-Type header by attaching it as a publish message attribute.

431 request header fields too large / 413 content too large

The following error occurs when Pub/Sub can't process the request because the content sent in the request is too large.

431 request header fields too Large / 413 content too large

This error occurs if the attributes in a Pub/Sub message exceed the header limit size of a server.

To resolve these issues, try the following solutions:

  • Turn off Write metadata.
  • Enable Dead Letter Queue (DLQ) on your push subscription. This redirects individual messages that can't be delivered. After, your subscription continues to operate, but the messages with errors are redirected to a separate topic for further analysis.

Check if payload unwrapping is enabled

  1. In the Google Cloud console, go to the Subscriptions page.

    Open Pub/Sub subscriptions

  2. Click the name of your service.

    The service detail page opens.

  3. In the configuration table, find the following values: Message data unwrapping and Write message metadata.

    The status of payload wrapping (enabled or disabled) is displayed in the corresponding table row.

What's next