What causes "Vercel API returned status code %d" in jeessy2/ddns-go?

Verify the Vercel API token is valid and has access to the domain (vercel whoami / test with curl -H "Authorization: Bearer ..." https://api.vercel.com/v4/domains)

jeessy2/ddns-go · error

Vercel API returned status code %d

Error message

Vercel API returned status code %d

What it means

Thrown by the Vercel DNS provider's request() helper (dns/vercel.go:181) whenever the Vercel API responds with a status code other than 200. The provider treats only 200 as success, so 4xx (bad token, invalid zone, wrong teamId) and 5xx (Vercel outage) both surface through this error. It is raised in listExistingRecords, createRecord and updateRecord. Unlike richer clients, it discards the response body, so the API's detailed reason is lost.

Source

Thrown at dns/vercel.go:181

	req, err := http.NewRequest(
		method,
		api,
		bytes.NewBuffer(payload),
	)
	if err != nil {
		return
	}
	req.Header.Set("Authorization", "Bearer "+v.DNS.Secret)
	req.Header.Set("Content-Type", "application/json")

	client := v.httpClient
	resp, err := client.Do(req)
	if err != nil {
		return err
	}
	if resp.StatusCode != 200 {
		return fmt.Errorf("Vercel API returned status code %d", resp.StatusCode)
	}
	if result != nil {
		err = util.GetHTTPResponse(resp, err, result)
	}
	return
}

View on GitHub (pinned to 5874c2e666)

Solutions

Verify the Vercel API token is valid and has access to the domain (vercel whoami / test with curl -H "Authorization: Bearer ..." https://api.vercel.com/v4/domains)
If the domain is in a team, set the teamId (ExtParam) correctly — an account-only token gets 403/404
Check the record payload: domain name, type and value must match what Vercel expects
If 429, back off and retry later; if 5xx, check Vercel status and retry

Defensive patterns

Strategy: try-catch

Validate before calling

// Go: preflight token/team access before provider calls
req, _ := http.NewRequest("GET", "https://api.vercel.com/v9/projects", nil)
req.Header.Set("Authorization", "Bearer "+token)
if teamID != "" {
    q := req.URL.Query(); q.Set("teamId", teamID); req.URL.RawQuery = q.Encode()
}
resp, err := http.DefaultClient.Do(req)
if err != nil || resp.StatusCode != 200 {
    return fmt.Errorf("Vercel token/teamId preflight failed: status %v", err)
}
resp.Body.Close()

Try / catch

// Go
err := provider.CreateRecord(rec)
if err != nil {
    if strings.Contains(err.Error(), "Vercel API returned status code") {
        if strings.Contains(err.Error(), "401") || strings.Contains(err.Error(), "403") {
            return fmt.Errorf("check Vercel token and teamId (ExtParam): %w", err)
        }
        if strings.Contains(err.Error(), "429") || strings.Contains(err.Error(), "5") {
            return retryWithBackoff(err)
        }
    }
    return err
}

Prevention

Verify the Bearer token is current and scoped to the right account/team
Always set teamId (ExtParam) when the domain belongs to a Vercel team
Respect rate limits — add backoff for bulk record updates
Check https://www.vercel-status.com when seeing 5xx

When it happens

Trigger: GET/POST/PATCH/DELETE to api.vercel.com returning 401/403 (invalid or revoked Bearer token), 400 (bad record payload or domain name), 404 (domain not in account or wrong teamId), 429 (rate limit), or 5xx (Vercel incident).

Common situations: Stale Vercel access token after rotation; using an account token while the domain lives in a team (or ExtParam/TeamId misconfigured); typo in the domain name; Vercel API rate limiting during bulk updates; Vercel platform incidents.

Related errors

AI-assisted analysis of jeessy2/ddns-go@5874c2e666 (2026-09-03). Data as JSON: /api/errors/6f4af089e047f8af. Report an issue: GitHub.