> ## Documentation Index > Fetch the complete documentation index at: https://docs.nomiq.site/llms.txt > Use this file to discover all available pages before exploring further. # Nomiq API Error Codes, Formats, and Troubleshooting Guide > Understand the Nomiq API error response format, every HTTP status code, its root cause, and how to resolve it in your integration. 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: ```json theme={null} { "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 ` 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](/api-reference/rate-limits) 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](https://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 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. 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. 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. 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](https://status.nomiq.com) to distinguish transient spikes from sustained incidents. ## Next Steps Review per-plan rate limit thresholds, response headers, and how to implement exponential backoff correctly. Resolve authentication errors by reviewing how to generate, store, and pass API keys correctly.