cloudflare/cloudflared · error

ErrAPINoSuccess

ErrAPINoSuccess

Error message

API call failed

What it means

ErrAPINoSuccess is a sentinel returned by parseResponseEnvelope when the Cloudflare API responds successfully at the HTTP level but the JSON envelope has success=false. It means Cloudflare accepted the request but rejected the operation, with details normally in the envelope's errors/messages fields.

Source

Thrown at cfapi/base_client.go:27

	"net/url"
	"strings"
	"time"

	"github.com/pkg/errors"
	"github.com/rs/zerolog"
	"golang.org/x/net/http2"
)

const (
	defaultTimeout  = 15 * time.Second
	jsonContentType = "application/json"
)

var (
	ErrUnauthorized = errors.New("unauthorized")
	ErrBadRequest   = errors.New("incorrect request parameters")
	ErrNotFound     = errors.New("not found")
	ErrAPINoSuccess = errors.New("API call failed")
)

type RESTClient struct {
	baseEndpoints *baseEndpoints
	authToken     string
	userAgent     string
	client        http.Client
	log           *zerolog.Logger
}

type baseEndpoints struct {
	accountLevel  url.URL
	zoneLevel     url.URL
	accountRoutes url.URL
	accountVnets  url.URL
}

var _ Client = (*RESTClient)(nil)

View on GitHub (pinned to 2253eeeb25)

Solutions

1. Inspect the envelope's `errors` and `messages` fields logged by the client for the underlying cause
2. Verify your API token has the correct zone/account and Cloudflare Tunnel permissions
3. Retry the operation if Cloudflare reports a transient error
4. Compare with errors.Is(err, cfapi.ErrAPINoSuccess) to branch on this case specifically

Example fix

// before
tunnels, err := client.ListTunnels(ctx, accountTag)
if err != nil {
    return err
}
// after
tunnels, err := client.ListTunnels(ctx, accountTag)
if errors.Is(err, cfapi.ErrAPINoSuccess) {
    return fmt.Errorf("cloudflare rejected the request; check token permissions and envelope error details: %w", err)
} else if err != nil {
    return err
}

func isAPINoSuccess(err error) bool { return errors.Is(err, cfapi.ErrAPINoSuccess) }

resp, err := client.Call(ctx, op, ...)
if errors.Is(err, cfapi.ErrAPINoSuccess) {
    // inspect logged envelope errors/messages, possibly retry
    return fmt.Errorf("cloudflare API rejected operation: %w", err)
}

When it happens

Trigger: Any API call whose response body decodes to a response envelope with the `success` field set to false — e.g. invalid API token permissions, account-level restrictions, or Cloudflare-side errors on tunnel endpoints.

Common situations: Using an API token lacking the Cloudflare Tunnel permissions; rate limiting or account suspensions surfacing as success=false; transient Cloudflare API failures during deploys.

Related errors

• Failed to fetch page. Server returned: %d
• API errors: %s
• Create Tunnel API call failed
• failed to get checksums: {0}
• failed to upload checksum: {0}

AI-assisted analysis of cloudflare/cloudflared@2253eeeb25 (2026-09-06). Data as JSON: /api/errors/b091d3f4a4f0bee5. Report an issue: GitHub.