Concepts

Errors

All errors return the same JSON envelope. Use error.type for branching, not the HTTP status alone.

Error envelope

Standard error responsejson

{
  "error": {
    "type": "invalid_request_error",
    "message": "Field \"customer_id\" is required.",
    "param": "customer_id"
  }
}

Error types

HTTP	type	When
400	`invalid_request_error`	Missing required field, malformed body, unknown parameter.
401	`authentication_error`	No API key, malformed key, revoked key, expired key.
403	`permission_error`	Org not on Pro plan, or read-only key attempting a write.
404	`not_found`	Resource doesn't exist or doesn't belong to your org.
409	`conflict`	Duplicate value or invalid state transition.
429	`rate_limit_error`	Too many requests in a short window.
500	`api_error`	Something on our end. Retryable.

Handling errors

A typical fetch wrapper:

async function renvoFetch(path, init) {
  const res = await fetch(`https://userenvo.com/api/v1${path}`, {
    ...init,
    headers: {
      'Authorization': `Bearer ${process.env.RENVO_API_KEY}`,
      ...init?.headers,
    },
  })
  if (!res.ok) {
    const { error } = await res.json()
    throw new RenvoError(error.type, error.message, res.status)
  }
  return res.json()
}