Common Issues

Connection issues

Authentication failed — invalid API key

Double-check that you copied the full API key from Braze without any trailing spaces. Also confirm the key is active — in Braze, go to Settings → Developer Console → API Keys and verify the key hasn't been deleted or rotated. If your organization rotates keys regularly, you may need to generate a new one and update it in your Coupler.io data flow.

Wrong REST endpoint — connection times out or returns 404

Braze hosts data on region-specific endpoints. Using the wrong URL (e.g., rest.iad-01.braze.com when your account is on rest.fra-01.braze.com) will cause the connection to fail. Find your correct endpoint in Braze under Settings → Developer Console — it's shown at the top of the page.

Missing data

Analytics entities return no rows or fewer rows than expected

This usually means the start_date is set too far in the future, or no data exists for the selected time window. Use the date picker to set a start date that covers the period you need. Also verify that the campaigns, canvases, or segments you're expecting have actually sent messages or logged activity during that period.

Certain campaigns or canvases are missing from the list entity

Braze's API only returns items the API key has permission to access. If you recently created a restricted API key, confirm it has read access to campaigns and canvases. Archived items may also be excluded from list responses depending on your Braze plan.

Permission errors

403 Forbidden when fetching a specific entity

Your API key may not have the required permission scope for that entity. In Braze, open the API key and check which endpoints are whitelisted. For example, to pull segments you need access to /segments/list and /segments/data_series. Add the missing endpoint permissions and re-run the data flow.

Braze allows you to restrict API keys to specific endpoints. If you're using a tightly scoped key, you'll need to explicitly allow each endpoint that Coupler.io calls.

Data discrepancies

Numbers in Coupler.io don't match the Braze dashboard

Braze dashboards often apply timezone adjustments and attribution windows that differ from raw API responses. The API returns data in UTC by default. If your Braze account is configured for a different timezone, totals may not align directly. Check your Braze workspace timezone settings and account for any attribution window differences when comparing numbers.

Canvas step-level metrics look aggregated rather than per-step

The canvases_analytics entity returns a steps_data field that contains nested per-step data. Depending on your destination, this nested structure may appear collapsed or as a single JSON string. You may need to use BigQuery or a transformation step to unnest this field for per-step reporting.

Rate limits

Sync fails partway through with a rate limit error

Braze enforces rate limits per API key — typically 250,000 requests per hour for most endpoints, but lower for some analytics endpoints. If you're syncing many entities in the same data flow or running very large date ranges, you may hit these limits. Try splitting entities into separate data flows or narrowing the date range per run.

Analytics endpoints like campaigns/data_series and canvases/data_series have stricter rate limits than list endpoints. Avoid running multiple analytics entities simultaneously if you're on a high-volume plan.