Troubleshooting

This page covers the most common issues you may encounter when using npayload, organised by category.

Authentication issues

Invalid credentials

Symptoms: API returns 401 AUTH_INVALID on every request.

Cause: The client ID or client secret is incorrect, or the API key has been revoked.

Resolution:

Verify that your client ID and secret match what is shown in the dashboard
Check that the API key has not been revoked or regenerated
Ensure you are using credentials for the correct app and environment

Expired tokens

Symptoms: Requests succeed initially but start returning 401 TOKEN_EXPIRED after some time.

Cause: The OAuth access token has expired.

Resolution: The @npayload/node SDK handles token refresh automatically. If you are making raw HTTP requests, request a new access token from the /oauth/token endpoint before retrying.

DPoP errors

Symptoms: API returns 401 DPOP_INVALID or 401 DPOP_NONCE_INVALID.

Cause: The DPoP proof JWT is malformed, expired, or bound to a different request.

Resolution:

Ensure the DPoP proof includes the correct HTTP method and URL
Check that the proof has not expired (proofs are valid for a short window)
If you receive DPOP_NONCE_INVALID, use the nonce from the DPoP-Nonce response header in your next request
The @npayload/node SDK handles DPoP proofs and nonce rotation automatically

Scope mismatch

Symptoms: API returns 403 SCOPE_INSUFFICIENT.

Cause: The access token does not include the required scope for the operation.

Resolution: Request a token with the appropriate scopes. Common scopes include messages:publish, messages:read, channels:manage, and subscriptions:manage.

Publishing issues

Channel not found

Symptoms: Publish returns 404 CHANNEL_NOT_FOUND.

Cause: The channel does not exist, has been archived, or belongs to a different app.

Resolution:

Verify the channel name is spelled correctly (channel names are case-sensitive)
Check that the channel exists in the same app as your API key
If the channel was recently archived, create a new one

Payload too large

Symptoms: Publish returns 400 PAYLOAD_TOO_LARGE.

Cause: The message payload exceeds the 256 KB limit.

Resolution:

Reduce the payload size by removing unnecessary fields
Store large data externally (for example, in object storage) and include a reference URL in the payload
For batch publishes, ensure the total batch payload does not exceed 10 MB

Rate limited

Symptoms: Publish returns 429 RATE_LIMITED.

Cause: You have exceeded the rate limit for your billing tier.

Resolution:

Check the Retry-After header and wait before retrying
Use batch publish to send multiple messages in a single request
Consider upgrading your billing tier for higher limits
See Limits and quotas for per-tier limits

Schema validation failed

Symptoms: Publish returns 422 VALIDATION_ERROR.

Cause: The message payload does not match the schema registered in the event catalogue for this channel.

Resolution:

Check the event catalogue for the expected schema on this channel
Validate your payload locally against the schema before publishing
If the schema has been updated, update your publisher to match the new version

Delivery issues

Webhook returns 401 or 403

Symptoms: Messages appear in the DLQ with a delivery error indicating 401 Unauthorized or 403 Forbidden.

Cause: Your webhook endpoint is rejecting requests from npayload.

Resolution:

Ensure your endpoint accepts requests from npayload's IP ranges
If your endpoint requires authentication, configure the subscription with the appropriate credentials
Verify that your HMAC signature validation logic is correct

Webhook returns 404

Symptoms: Deliveries fail with 404 Not Found.

Cause: The webhook URL is incorrect or the endpoint has been removed.

Resolution:

Verify the webhook URL in your subscription configuration
Check that the endpoint is deployed and accessible
Update the subscription with the correct URL if it has changed

Webhook returns 500

Symptoms: Deliveries fail intermittently with 500 Internal Server Error.

Cause: Your webhook endpoint is experiencing errors.

Resolution:

Check your endpoint's logs for error details
npayload will retry the delivery according to your retry policy
If the errors are persistent, the circuit breaker will open (see below)

Webhook timeout

Symptoms: Deliveries fail with a timeout error.

Cause: Your webhook endpoint is taking too long to respond. npayload waits up to 30 seconds for a response.

Resolution:

Optimise your endpoint to respond within 30 seconds
Accept the webhook quickly and process the message asynchronously
Return a 202 Accepted status immediately, then process in the background

Circuit breaker open

Symptoms: Deliveries fail immediately with 503 CIRCUIT_OPEN. No requests reach your endpoint.

Cause: The circuit breaker has opened because your endpoint has returned too many consecutive 5xx errors.

Resolution:

Fix the underlying issue with your endpoint
The circuit breaker will automatically close after the recovery window (typically 60 seconds)
Pending messages will be retried once the circuit closes
If messages have moved to the DLQ, replay them after your endpoint is healthy

All retries exhausted

Symptoms: Messages appear in the DLQ with status RETRIES_EXHAUSTED.

Cause: npayload has attempted delivery the maximum number of times and all attempts failed.

Resolution:

Fix the issue with your endpoint
Replay the DLQ entries from the dashboard or via the API
Consider adjusting your retry policy (more attempts, longer backoff)

Subscription issues

Subscription paused

Symptoms: No messages are being delivered even though messages are being published.

Cause: The subscription has been paused, either manually or automatically due to repeated failures.

Resolution:

Check the subscription status in the dashboard
Resume the subscription via the dashboard or API
If it was paused automatically, fix the underlying delivery issue first

Consumer group rebalancing

Symptoms: Brief gaps in delivery or duplicate messages during consumer group membership changes.

Cause: A consumer joined or left the group, triggering a rebalance.

Resolution: This is normal behaviour. During rebalancing, some messages may be redelivered. Design your consumers to be idempotent. The rebalance completes within seconds.

Offset out of range

Symptoms: Stream consumer returns an error indicating the offset is out of range.

Cause: The requested offset points to a message that has been deleted due to retention policy expiry.

Resolution:

Seek to the earliest available offset using earliest
Seek to the latest offset using latest to resume from the current position
Increase your channel's retention period to prevent future data loss

DLQ issues

Messages appearing in DLQ

Symptoms: Messages are accumulating in the dead letter queue.

Cause: Delivery to the subscriber's endpoint is failing repeatedly.

Resolution:

Check the DLQ entries for error details (status code, error message)
Fix the endpoint issue
Replay the DLQ entries once the endpoint is healthy

DLQ entries include the original message, delivery attempt count, last error, and timestamp. Use this information to diagnose the root cause.

Replay fails

Symptoms: Replaying DLQ entries results in the same failure.

Cause: The underlying issue with the endpoint has not been resolved.

Resolution:

Verify your endpoint is healthy by sending a test request
Check that the endpoint URL has not changed
Fix the endpoint, then retry the replay

DLQ full

Symptoms: New delivery failures are being dropped instead of added to the DLQ.

Cause: The DLQ has reached its entry limit for your billing tier.

Resolution:

Purge processed or obsolete DLQ entries
Replay and fix outstanding entries
Upgrade your tier for higher DLQ limits (see Limits and quotas)

SDK issues

Connection refused

Symptoms: SDK throws a connection error when initialising or making requests.

Cause: The SDK cannot reach the npayload API.

Resolution:

Check that your network allows outbound HTTPS connections
Verify you are using the correct region endpoint
Check the npayload status page for any ongoing incidents

Timeout configuration

Symptoms: Requests are timing out before completing.

Cause: The default timeout may be too short for your network conditions.

Resolution: Configure a longer timeout in the SDK:

import { NPayload } from '@npayload/node';

const npayload = new NPayload({
  clientId: process.env.NPAYLOAD_CLIENT_ID,
  clientSecret: process.env.NPAYLOAD_CLIENT_SECRET,
  timeout: 30000, // 30 seconds
});

Version mismatch

Symptoms: TypeScript compilation errors or unexpected behaviour after updating the SDK.

Cause: Breaking changes in a major SDK version.

Resolution:

Check the changelog for breaking changes
Follow the migration guide for your version
Pin to a specific version in package.json if you need stability

Next steps

Error codes for the complete error reference
Rate limits for rate limit details and best practices
FAQ for answers to common questions

Was this page helpful?

Troubleshooting

On this page