Errors and limits

A request that doesn’t work answers with a 4xx or 5xx status and:

{
  "error": {
    "code": "invalid_value",
    "message": "This value takes a number, like 42 or 3.5.",
    "details": null
  }
}

Act on code; show message to people (it’s written for them). details sometimes says more, such as which fields were refused.

• 400 invalid: some fields weren’t accepted; details lists them. Other 400 codes name the problem (invalid_value, invalid_item, invalid_playlist).
• 401 unauthenticated: no key, a mistyped key, or a key that was switched off.
• 402 plan_required: the account isn’t on Pro. Other 402s: plan_limit_screens, plan_limit_locations, storage_full, convert_limit, contact_us.
• 403 insufficient_scope: the key can’t do that (see API keys). 403 console_only: only a person in the console can do that.
• 404 not_found: no such thing in this account.
• 409: a conflict, such as conflict (a name already used), menu_changed or busy. Read it again and retry.
• 429 rate_limited: too many requests. Wait, then retry.
• 500 internal or 503 busy: our side. Retry after a few seconds, waiting longer each time.

Limits

• Live values: up to 60 updates a minute per value and 20,000 a day per account; up to 100 values.
• Menus: up to 400 lines in one /items call.
• Keys: up to 20 at once. Webhooks: up to 10 addresses.
• Uploads: files up to 4 GB, videos up to 10 minutes, pictures up to 64 megapixels.