Errors

HelaMesh uses standard HTTP status codes:

Code	Meaning
200	Success
201	Resource created
400	Bad request — validation failed
401	Missing or invalid API key
403	Authenticated but not authorized for this resource
404	Resource not found
409	Conflict (e.g. duplicate open invoice)
429	Rate limited
5xx	HelaMesh error — safe to retry with backoff

Error response shape

409 Conflict

{
  "statusCode": 409,
  "message": "An open invoice for the same address and amount already exists. Wait for it to complete/expire, or use a different amount.",
  "error": "Conflict"
}

Retry semantics

• 4xx errors are your problem. Fix the request and retry. Do not retry 400/401/403/404/409 blindly.
• 5xx errors are our problem. Retry with exponential backoff (start at 1s, cap at 30s, give up after ~5 attempts).
• 429 rate limit. Honor the Retry-After header if present, otherwise back off at least 1 minute before retrying.