Errors - Diagrams.so

Every error returns the same JSON envelope with a stable machine-readable code, a human message, and a request_id you can quote to support.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Slow down and retry.",
    "request_id": "req_8f2a...",
    "details": {}
  }
}

Status codes

Status	`code` (examples)	Meaning and action
`400`	`VALIDATION_ERROR`	Malformed request. Fix the body and retry.
`401`	`UNAUTHORIZED`	Missing, invalid, or expired key. Check the `Authorization` header.
`402`	`QUOTA_EXCEEDED`	Kept for compatibility. Unused while both plans are unlimited.
`403`	`FORBIDDEN`	Key lacks the required scope.
`403`	`UPGRADE_REQUIRED`	The action needs Paid, for example `export?format=drawio` on Free. Use `format=svg`, or upgrade at diagrams.so/pricing.
`404`	`NOT_FOUND`	No such resource, or not yours.
`409`	`CONFLICT`	Idempotency or state conflict.
`422`	`UNPROCESSABLE`	Semantically invalid input.
`429`	`RATE_LIMITED`	Too many requests. Back off and retry. See Rate limits.
`5xx`	`INTERNAL`, `SERVICE_UNAVAILABLE`	Transient. Retry with backoff.

Retrying safely

Retryable: 429 and 5xx. Use exponential backoff.
Not retryable without changes: 400, 401, 402, 403, 404, 422.
On create calls, send an Idempotency-Key so a retry never duplicates a diagram.

Getting support

Include the request_id from the error envelope when you contact support. It lets us find the exact request.