Nomiq API Error Codes, Formats, and Troubleshooting Guide

When a Nomiq API request cannot be completed successfully, the API returns a standard HTTP error status code alongside a JSON response body that gives you the information you need to diagnose and fix the problem. Understanding the error format and the meaning of each code will save you significant debugging time as you build and maintain your integration.

Error Response Format

Every error response from the Nomiq API — regardless of status code — returns a JSON object with a top-level error key containing three fields:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Required parameter 'project_id' is missing from the request body.",
    "code": "missing_required_param"
  }
}

Field	Type	Description
`type`	string	A broad category for the error. Useful for top-level branching in error handlers. Values: `invalid_request_error`, `authentication_error`, `authorization_error`, `not_found_error`, `validation_error`, `rate_limit_error`, `api_error`.
`message`	string	A human-readable description of what went wrong. Suitable for internal logging and debugging. Do not display this string directly to your end users.
`code`	string	A machine-readable error identifier for programmatic handling (for example, `missing_required_param`, `invalid_api_key`, `rate_limit_exceeded`).

HTTP Status Code Reference

The Nomiq API uses standard HTTP status codes. Codes in the 2xx range indicate success. Codes in the 4xx range indicate a problem with your request that you must fix before retrying. Codes in the 5xx range indicate a transient problem on Nomiq’s infrastructure that you can safely retry.

HTTP Status	Error Code	Meaning	Resolution
`400`	`invalid_request_error`	The request was malformed — a required parameter is missing, a value is the wrong type, or the request body is not valid JSON.	Inspect the `message` field to identify the exact parameter that failed validation. Cross-reference your request body against the endpoint’s schema in this reference.
`401`	`authentication_error`	No API key was provided, the `Authorization` header is malformed (missing the `Bearer` prefix), or the key has been revoked.	Confirm your `Authorization: Bearer <key>` header is present and correctly formatted. Check the Dashboard to verify the key has not been revoked.
`403`	`authorization_error`	Your API key is valid but your workspace does not have permission to perform this action — typically because your billing plan does not include the requested feature, or your workspace has exceeded its monthly quota with an unpaid invoice.	Log into the Nomiq Dashboard and review your plan tier and billing status under the Billing tab.
`404`	`not_found_error`	The resource identified by the ID in your request URL does not exist, or it belongs to a different workspace than the one your API key is scoped to.	Double-check the `project_id`, `brand_id`, or other resource ID in your request. Confirm it was created under the same workspace as your current API key.
`422`	`validation_error`	The request body is syntactically valid JSON, but the content failed semantic validation — for example, a brand generation prompt that is too short, contains disallowed content, or exceeds the maximum character limit.	Read the `message` field for the specific validation rule that was violated and adjust your prompt or parameters accordingly.
`429`	`rate_limit_error`	Your workspace has exceeded the per-minute request limit for the current endpoint. The response includes a `Retry-After` header specifying how many seconds to wait before retrying.	Implement exponential backoff with jitter in your retry logic. See the Rate Limits guide for per-plan thresholds.
`500`	`api_error`	An unexpected error occurred on Nomiq’s servers. This is not caused by your request.	Retry the request after a short delay using the same `Idempotency-Key` if applicable. Check status.nomiq.com for any active incidents. If the error persists beyond five minutes, contact support.

Retry Strategy

Not all errors should be retried — only 429 and 5xx responses are candidates for automatic retry. Retrying 400, 401, 403, or 404 errors will never succeed because they indicate a fundamental problem with your request or credentials, and repeated retries only waste your quota. For 429 and 500 errors, use exponential backoff: wait one second before the first retry, two seconds before the second, four before the third, and so on, up to a maximum of five retries. Add a small random jitter (50–200ms) to each wait interval to prevent multiple clients from all retrying at the exact same moment.

Do not automatically retry 400, 401, 403, or 404 errors. These status codes mean your request has a fundamental problem — a missing parameter, an invalid key, or a non-existent resource — that will not resolve itself on retry. Fix the underlying issue in your request before sending it again.

Common Error Scenarios

Every request returns 401, but my API key looks correct.

The most frequent cause is a whitespace or formatting issue in the Authorization header. The correct format is exactly Authorization: Bearer sk_live_xxxx — with a single space between Bearer and the key, and no trailing whitespace. Log the raw header string immediately before it is sent and verify it character by character. Also check that your environment variable is resolving to the full key value and not an empty string or the literal text $NOMIQ_API_KEY.A second common cause is environment mismatch: sending a Test key (sk_test_...) to api.nomiq.com or a Live key (sk_live_...) to sandbox.nomiq.com. Each key type is only valid on its matching base URL.

Generation requests return 422 with 'prompt_validation_failure'.

This error fires when your brand generation prompt fails semantic validation before it reaches the AI engine. Common triggers include: prompts shorter than 10 characters, prompts that exceed 2,000 characters, or prompts that contain disallowed content categories. Check the message field for the specific rule violation. If your application accepts freeform user input, add client-side validation before submitting to the API — for example, enforce a minimum length and strip any content that violates the policy listed in the Generation API reference.

I'm getting 404 on a project_id that I just created.

A 404 on a recently created project almost always means an environment mismatch. Projects created via the sandbox (sandbox.nomiq.com/v1) are isolated from the production environment (api.nomiq.com/v1). If you created the project with a Test key and are now querying it with a Live key (or vice versa), the project will appear not to exist. Ensure your key type and base URL are consistent across your entire request sequence.

Sporadic 500 errors appear on generation requests during peak hours.

Transient 500 errors on generation endpoints during high-traffic windows typically indicate brief GPU queue pressure on Nomiq’s infrastructure. These errors self-resolve within seconds. Implement idempotent retries: include an Idempotency-Key header on every generation POST, then retry with the same key after a two-second delay. If Nomiq processed the original request before the error, the retry will return the original result without triggering a second generation. Monitor status.nomiq.com to distinguish transient spikes from sustained incidents.

Next Steps

Rate Limits

Review per-plan rate limit thresholds, response headers, and how to implement exponential backoff correctly.

Authentication

Resolve authentication errors by reviewing how to generate, store, and pass API keys correctly.

​Error Response Format

​HTTP Status Code Reference

​Retry Strategy

​Common Error Scenarios

​Next Steps

Rate Limits

Authentication

Error Response Format

HTTP Status Code Reference

Retry Strategy

Common Error Scenarios

Next Steps