miro-common-errors

name	miro-common-errors
description	Diagnose and fix Miro REST API v2 errors by HTTP status code. Use when encountering Miro API errors, debugging failed requests, or troubleshooting authentication and permission issues. Trigger with phrases like "miro error", "fix miro", "miro not working", "debug miro", "miro 401", "miro 403", "miro 429".
allowed-tools	Read, Grep, Bash(curl:*)
version	1.7.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","miro","errors","troubleshooting"]
compatibility	Designed for Claude Code

Miro Common Errors

Overview

Quick reference for Miro REST API v2 errors organized by HTTP status code, with real error response bodies and proven fixes.

Prerequisites

• Access token configured
• curl available for diagnostic requests

Quick Diagnostic

Instructions

Run the diagnostic requests in order, identify the returned HTTP status, then use the matching entry in the error reference. Apply one corrective action at a time and repeat the original request to confirm the failure is resolved.

Output

The investigation produces a status code, an identified cause, and a verified remediation step. Preserve the response code and any request or board identifiers needed for escalation without exposing access tokens.

Examples

Start with the connectivity check below using a non-production token. For example, a 401 result directs you to the token-expiry entry, while a 429 result directs you to the backoff guidance.

# 1. Verify API connectivity
curl -s -o /dev/null -w "%{http_code}" https://api.miro.com/v2/boards \
  -H "Authorization: Bearer $MIRO_ACCESS_TOKEN"

# 2. Check token validity
curl -s https://api.miro.com/v1/oauth-token \
  -H "Authorization: Bearer $MIRO_ACCESS_TOKEN" | jq

# 3. Check Miro status page
curl -s https://status.miro.com/api/v2/status.json | jq '.status.description'

Error Reference

400 — Bad Request

{
  "status": 400,
  "code": "invalidInput",
  "message": "Could not resolve the value for parameter: data.content",
  "context": {