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_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Max 120 requests per minute.",
    "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`	Out of credits for a billable action. Top up.
`403`	`FORBIDDEN`	Key lacks the required scope.
`404`	`NOT_FOUND`	No such resource, or not yours.
`409`	`CONFLICT`	Idempotency or state conflict.
`422`	`UNPROCESSABLE`	Semantically invalid input.
`429`	`RATE_LIMIT_EXCEEDED`	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 billable create calls, send an Idempotency-Key so a retry never duplicates a diagram or double-charges.

Getting support

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