Errors

{
  "error": {
    "type": "validation_error",
    "code": "invalid_query_parameter",
    "message": "Number must be less than or equal to 100",
    "param": "limit",
    "docUrl": "https://docs.replyful.com/errors/invalid_query_parameter",
    "requestId": "req_01HK7GD3H6ZSQ0Y2A5B3C4DEFG"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Missing Authorization header. Provide `Authorization: Bearer rfl_…`.",
    "docUrl": "https://docs.replyful.com/errors/missing_api_key",
    "requestId": "req_..."
  }
}

{
  "error": {
    "type": "validation_error",
    "code": "invalid_query_parameter",
    "message": "Number must be less than or equal to 100",
    "param": "limit",
    "docUrl": "https://docs.replyful.com/errors/invalid_query_parameter",
    "requestId": "req_..."
  }
}

{
  "error": {
    "type": "validation_error",
    "code": "conflicting_date_range",
    "message": "Cannot filter by both createdAt and updatedAt date ranges.",
    "docUrl": "https://docs.replyful.com/errors/conflicting_date_range",
    "requestId": "req_..."
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "too_many_requests",
    "message": "Rate limit exceeded. Slow down and try again shortly.",
    "docUrl": "https://docs.replyful.com/errors/too_many_requests",
    "requestId": "req_..."
  }
}

async function callReplyful(path: string, init?: RequestInit) {
  const res = await fetch(`https://api.replyful.com${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.REPLYFUL_API_KEY}`,
      ...init?.headers,
    },
  });

  if (res.ok) {
    return res.json();
  }

  const body = await res.json().catch(() => ({}));
  const requestId = res.headers.get("Request-Id") ?? body.error?.requestId;

  // Branch on type for high-level handling.
  switch (body.error?.type) {
    case "authentication_error":
      throw new Error(`Replyful auth failed (${requestId}). Check your API key.`);
    case "rate_limit_error": {
      const retryAfter = Number(res.headers.get("Retry-After") ?? "1");
      throw new RateLimitError(retryAfter, requestId);
    }
    case "validation_error":
      throw new Error(`Validation failed: ${body.error.message} (${requestId})`);
    default:
      throw new Error(`Replyful API error (${requestId}): ${body.error?.message ?? res.statusText}`);
  }
}