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 <jeremy@intentsolutions.io>
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.

```bash
# 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

```json
{
  "status": 400,
  "code": "invalidInput",
  "message": "Could not resolve the value for parameter: data.content",
  "context": { "fields": [{ "field": "data.content", "message": "Required" }] }
}
```

**Common causes:**

- Missing required fields in request body
- Wrong data types (string instead of number for position)
- Invalid enum values (e.g., `shape: 'oval'` — correct is `shape: 'circle'`)

**Fix:** Cross-reference your request body with the [REST API reference](https://developers.miro.com/docs/rest-api-reference-guide). Each item type has specific required fields.

**Sticky note required fields:** `data.content`, `data.shape` (`square` or `rectangle`)
**Shape required fields:** `data.shape` (see `miro-sdk-patterns` for valid shapes)
**Connector required fields:** `startItem.id`, `endItem.id`

---

### 401 — Unauthorized

```json
{
  "status": 401,
  "code": "tokenNotProvided",
  "message": "Access token is not provided"
}
```

```json
{
  "status": 401,
  "code": "tokenExpired",
  "message": "Access token has expired"
}
```

**Common causes:**

- Missing `Authorization: Bearer <token>` header
- Access token expired (tokens last 3599 seconds / ~1 hour)
- Using client_id/client_secret instead of access_token

**Fix:**

```bash
# Check if token is set
echo "Token length: ${#MIRO_ACCESS_TOKEN}"

# Refresh expired token
curl -X POST https://api.miro.com/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=$MIRO_CLIENT_ID" \
  -d "client_secret=$MIRO_CLIENT_SECRET" \
  -d "refresh_token=$MIRO_REFRESH_TOKEN"
```

---

### 403 — Forbidden

```json
{
  "status": 403,
  "code": "insufficientPermissions",
  "message": "Required scopes: boards:write",
  "context": { "requiredScopes": ["boards:write"] }
}
```

**Common causes:**

- Token lacks required OAuth scope
- User does not have board-level permission (viewer trying to write)
- Team-level restrictions prevent the operation

**Fix:**

1. Check which scopes your token has vs. what the endpoint requires
2. Update scopes in your Miro app settings at https://developers.miro.com
3. Re-authorize the user to get a token with updated scopes

| Endpoint Category | Required Scope |
|-------------------|---------------|
| GET boards/items | `boards:read` |
| POST/PATCH/DELETE boards/items | `boards:write` |
| GET team/members | `team:read` |
| Organization endpoints | `organizations:read` |

---

### 404 — Not Found

```json
{
  "status": 404,
  "code": "boardNotFound",
  "message": "Board not found or access denied"
}
```

**Common causes:**

- Board ID is wrong or has been deleted
- Item ID references a deleted item
- Token owner does not have access to the board

**Fix:**

```bash
# Verify board exists and you have access
curl -s https://api.miro.com/v2/boards/$BOARD_ID \
  -H "Authorization: Bearer $MIRO_ACCESS_TOKEN" | jq '.id, .name'

# List boards to find correct ID
curl -s "https://api.miro.com/v2/boards?limit=10" \
  -H "Authorization: Bearer $MIRO_ACCESS_TOKEN" | jq '.data[] | {id, name}'
```

---

### 409 — Conflict

```json
{
  "status": 409,
  "code": "duplicateTagTitle",
  "message": "A tag with this title already exists"
}
```

**Common causes:**

- Creating a tag with a title that already exists on the board
- Concurrent modifications to the same item

**Fix:** Fetch existing tags first and reuse their IDs instead of creating duplicates.

---

### 429 — Rate Limited

```json
{
  "status": 429,
  "code": "rateLimitExceeded",
  "message": "Rate limit exceeded"
}
```

**Response headers:**

```
X-RateLimit-Limit: 100000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1700000060
Retry-After: 30
```

**Fix:** Honor the `Retry-After` header. See `miro-rate-limits` for complete backoff patterns. The global limit is 100,000 credits/minute.

---

### 500 / 502 / 503 — Server Error

**Common causes:**

- Miro platform issue (check https://status.miro.com)
- Transient infrastructure error

**Fix:**

1. Check Miro status page
2. Retry with exponential backoff (see `miro-rate-limits`)
3. If persistent (>5 min), it is a Miro-side issue — enable fallback mode

## Programmatic Error Handler

```typescript
async function handleMiroError(response: Response, context: string): Promise<never> {
  const body = await response.json().catch(() => ({}));

  switch (response.status) {
    case 401:
      console.error(`[Miro:${context}] Token expired/invalid. Refreshing...`);
      // Trigger token refresh
      break;
    case 403:
      console.error(`[Miro:${context}] Missing scopes: ${body.context?.requiredScopes?.join(', ')}`);
      break;
    case 429:
      const retryAfter = response.headers.get('Retry-After') ?? '60';
      console.warn(`[Miro:${context}] Rate limited. Retry after ${retryAfter}s`);
      break;
    default:
      console.error(`[Miro:${context}] ${response.status}: ${body.message ?? 'Unknown error'}`);
  }

  throw new Error(`Miro API ${response.status}: ${body.message ?? context}`);
}
```

## Escalation Path

1. Run diagnostics above
2. Collect evidence with `miro-debug-bundle`
3. Check https://status.miro.com
4. File support ticket with request ID (from `X-Request-Id` response header)

## Error Handling

If the diagnostic result does not match a documented status or persists after the corrective step, stop retrying destructive operations, capture the sanitized response details, and follow the escalation path. Treat repeated `5xx` responses as a service-health incident rather than a credential problem.

## Resources

- [Miro Status Page](https://status.miro.com)
- [REST API Reference Guide](https://developers.miro.com/docs/rest-api-reference-guide)
- [Permission Scopes](https://developers.miro.com/reference/scopes)
- [Rate Limiting](https://developers.miro.com/reference/rate-limiting)

## Next Steps

For comprehensive debugging, see `miro-debug-bundle`.