What do common API errors mean?

This guide explains the HTTP status codes you might see when calling the Nozzle API, what causes each one, and how to fix it.

For the basics of authenticating with the API and finding your IDs, see How do I authenticate with the Nozzle API?

Quick reference

400 Bad Request

The server understood your request but rejected it because something in the body or URL is invalid.

Common causes:

• Missing a required field in the request body. PUT /keywordSources/{id} expects the complete object, not a partial one (see How do keyword sources work? for a full example)
• On a Reporting API call, a missing workspaceId or teamId. The response names the field, for example required argument is missing: teamId. Both IDs belong in the JSON body. Sending them as HTTP headers doesn't count, and you'll get the same 400
• A localeId, brandId, or other reference that doesn't exist in your workspace
• Malformed JSON — a missing comma, unclosed bracket, or trailing comma in the request body
• A (criteria_id, language) combination that doesn't have a localeId in Nozzle's catalog yet (see How do Nozzle locales work?)
• Invalid rrule string in a schedule

How to fix:

• Validate the JSON body before sending — most languages have a built-in JSON parser that'll catch syntax errors
• Compare your request body against a known-good example (e.g., the PUT example in How do keyword sources work?)
• If the response includes an error message, read it carefully — it usually points at the offending field

403 Forbidden

The most common error you'll encounter. Nozzle's API returns 403 for both authentication failures and resource access issues, rather than distinguishing them with separate 401 and 403 codes. If you see a 403, work through the possibilities in order:

Authentication issues:

• Missing Authorization header entirely
• Header format wrong — should be Authorization: Token <your_api_key> (note the word "Token" and a space; not "Bearer")
• API key is wrong, expired, or has been rotated
• Extra whitespace or a truncated key

Resource access issues:

• The workspaceId in your request doesn't match the workspace your API key was issued for
• You're trying to access a keyword source, team, or other resource that lives in a different workspace (on the Reporting API, a teamId from another workspace returns 404 instead; see below)
• The resource ID you're referencing doesn't exist (Nozzle returns 403 rather than 404 for missing resources, to avoid leaking which IDs are valid)

How to fix:

• Verify the header format exactly: Authorization: Token <your_api_key>
• Confirm your API key is current and hasn't been rotated. If in doubt, create a new one.
• Verify the workspaceId, teamId, and keywordSourceId in your request all belong to the same workspace
• Double-check IDs against the URL of the resource in app.nozzle.io

404 Not Found

Returned when you provide a real ID paired with a workspaceId that doesn't own it. That happens in two places:

• Admin API: a real keyword source ID sent with the wrong workspaceId
• Reporting API: a teamId (project ID) in the request body that belongs to a different workspace than the body's workspaceId

For most other "resource doesn't exist" cases, Nozzle returns 403 instead (see above).

The response body usually reads {"success":false,"message":"sql: no rows in result set"}. It isn't a permissions problem: API tokens can read every project in their workspace, so there's no permission to add to the token's user. It means the IDs you sent don't belong together.

Common causes:

• Copy-paste error: correct keyword source ID or project ID, but the workspaceId from somewhere else
• You have access to multiple workspaces and are referencing IDs from different ones in the same request
• The resource was moved or the workspace was reorganized

How to fix:

• Check that workspaceId and every other ID in the request belong to the same workspace

• For a Reporting API call, list the workspace's projects and confirm your teamId is among them:

  curl 'https://api.nozzle.app/teams?workspaceId=<workspace_id>' \
    -H 'authorization: Token <your_api_key>'

  Each project's id in the response is a valid teamId for that workspace. If the list comes back empty, check the workspaceId before the teamId.

• Cross-check IDs in the URL of app.nozzle.io — the workspaceId and keyword source ID both appear in the app URLs

409 Conflict

Your request conflicts with the current state of the resource. The server is refusing to apply the change to prevent data loss or inconsistency.

In practice, 409 responses on Nozzle's API are uncommon and typically limited to DELETE operations against resources with dependencies (see below). If you encounter a 409 on a PUT or POST request, contact us with the request details so we can investigate.

On DELETE requests

409 Conflict on DELETE usually means the resource is in a state that prevents deletion — for example, an in-progress operation, a dependent resource that needs to be removed first, or a transient lock.

How to fix:

• Wait briefly and retry (transient locks usually clear within seconds)
• Verify there are no dependent resources (e.g., a project may need its keyword sources removed before it can be deleted)
• If you're seeing repeated 409s on bulk deletes, reach out — we can often help clean up server-side faster than retrying

429 Too Many Requests

Nozzle doesn't currently enforce explicit per-customer rate limits, but well-designed API integrations should plan for them anyway in case that changes. If you start seeing 429 responses in the future, the standard patterns apply: implement exponential backoff, batch requests where you can (e.g., update many phrases in a single PUT instead of calling PUT once per phrase), and contact us if you're consistently hitting limits that block your integration.

500–504 Server errors

Something went wrong on Nozzle's end. These are usually transient.

How to fix:

• Retry the request after a short delay (usually a few seconds is enough)
• If a request consistently returns 500 or higher across multiple retries, the request itself may be triggering a server bug — contact us with the request details (URL, body, time of request) so we can investigate
• Build retry logic into any production integration — transient server errors happen with any API

It worked, but the result wasn't what I expected

Not all problems show up as error codes. A few patterns to watch for:

• A PUT seems to have created a new keyword source instead of updating the existing one. Check that you sent the correct id in the URL path. PUT requires the full object in the body — if you sent an object that mismatched the URL id, the API may not have applied the update where you expected.
• Phrases I expected to be removed are still tracked. Remember that PUT /keywordSources/{id} requires the full object — if you sent a partial body, missing fields may have been preserved as-is rather than removed. Always GET the full object, modify it, and PUT it back.
• A Reporting API call returned 200 with an empty series. A segment ID that doesn't exist doesn't cause an error. The call succeeds and returns "series": []. Check that each ID in segmentIds is one of your segments, which are listed on the Segments page (see How do I create custom segments?), and check the other IDs in filters the same way.
• Devices or locales seem to have been multiplied unexpectedly. In a basic keyword source, every phrase is tracked against every locale and device. If you have 10 phrases × 4 locales × 2 devices, you'll get 80 keyword combinations. For per-phrase targeting, use a json keyword source.

Need help?

If you're hitting an error that isn't covered here — or one that's covered here but isn't behaving the way the doc describes — reach out with the request URL, request body (redact your API key), and the response status and body. We'd rather work through it with you than have you stuck.