Errors

When a request fails, the API returns an HTTP status code that tells you what went wrong. This page covers every error you might encounter and how to resolve it.

Error responses

400 Bad Request

The request body is missing required fields or contains invalid values.

Common causes:

• blocks array is empty or missing
• panelId is outside the 1–4 range
• A hex color value is malformed (must be #RRGGBB)
• density, alignX, or alignY has an unrecognized value
• Request body isn't valid JSON

Fix: Check your request body against the field reference. The response body includes details about which field failed validation.

401 Unauthorized

The request is missing an API key, or the key is invalid or revoked.

Common causes:

• The X-Api-Key header is missing
• The API key was revoked
• The API key was copied incorrectly (check for extra spaces)

Fix: Verify your API key with pushtodisplay auth status or check the web portal. If the key was revoked, create a new one.

403 Forbidden

The API key is valid, but it doesn't have access to the specified board.

Common causes:

• The boardId belongs to a different account
• The board exists but isn't owned by the authenticated user

Fix: Make sure you're using the correct board ID. Run pushtodisplay boards list to see your boards.

404 Not Found

The specified board doesn't exist.

Common causes:

• The boardId is wrong or has a typo
• The board was deleted

Fix: Check the board ID. Use pushtodisplay boards list or the web portal to find the correct ID.

409 Conflict

You've exceeded a quota for your subscription tier.

Common causes:

• Monthly message limit reached
• Board count limit reached
• Active stream limit reached

Fix: Check your current usage in the mobile app. You can upgrade your tier for higher limits, or wait for the next billing cycle (for monthly message limits). See Rate Limits for quota details by tier.

413 Payload Too Large

The request body exceeds your tier's maximum message size.

Limits by tier:

Fix: Reduce the size of your payload — fewer blocks, shorter text, or fewer style options. If you regularly need larger payloads, consider upgrading your tier.

429 Too Many Requests

You're sending requests faster than your tier allows.

Push To Display uses a token bucket rate limiter. Each tier has a per-second rate and a burst allowance:

Fix: Add a short delay between requests. The burst bucket refills at the per-second rate, so brief pauses are usually enough. For CI/CD pipelines with multiple steps, space out your Push To Display calls.