Noteboxd API Error Codes and Troubleshooting Guide

When a Noteboxd API call fails, the response body contains a structured error object with a machine-readable code and a human-readable message. Use the code field in your application logic to branch on specific failure conditions — don’t rely on the message string, as it may change. The optional details field provides additional context when available.

Error response format

Every failed request returns a consistent JSON envelope:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid.",
    "details": null
  }
}

Error code reference

HTTP Status	Code	Meaning	Fix
400	`INVALID_QUERY`	A query parameter or request body is invalid	Check required parameters and data types
401	`MISSING_API_KEY`	No `Authorization` header was sent	Add `Authorization: Bearer nb_live_...`
401	`INVALID_API_KEY`	The key is malformed or unrecognized	Verify the key in your developer portal
402	`INSUFFICIENT_BALANCE`	Your prepaid balance is zero	Top up at developers.noteboxd.com
404	`NOT_FOUND`	The requested resource does not exist	Check the ID or slug is correct
429	`RATE_LIMIT_EXCEEDED`	Daily call quota exhausted	Wait for reset (see `X-RateLimit-Reset` header)
500	`INTERNAL_ERROR`	Unexpected server error	Retry with backoff; contact support if persistent

4xx errors are not retryable without first fixing the underlying issue. Only 429 RATE_LIMIT_EXCEEDED and 500 INTERNAL_ERROR responses should be retried — and only after addressing the root cause or waiting for the rate-limit window to reset.

Handling errors in code

The example below shows a practical pattern for catching and branching on Noteboxd error codes in JavaScript:

const res = await fetch(
  'https://api.noteboxd.com/v1/fragrances/unknown-id',
  { headers: { Authorization: `Bearer ${process.env.NOTEBOXD_API_KEY}` } }
);

if (!res.ok) {
  const { error } = await res.json();
  switch (error.code) {
    case 'MISSING_API_KEY':
    case 'INVALID_API_KEY':
      throw new Error('Check your API key configuration');
    case 'INSUFFICIENT_BALANCE':
      throw new Error('Top up your Noteboxd balance');
    case 'RATE_LIMIT_EXCEEDED':
      // retry after reset
      break;
    case 'NOT_FOUND':
      // handle gracefully
      break;
    default:
      throw new Error(`API error: ${error.message}`);
  }
}

The X-RateLimit-Reset response header contains a Unix timestamp indicating when your daily quota resets. Read this value before scheduling a retry so you don’t waste calls.

Retrying on 500 errors

INTERNAL_ERROR responses indicate an unexpected problem on Noteboxd’s servers. When you encounter one, retry the request using exponential backoff — for example, wait 1 second before the first retry, 2 seconds before the second, 4 seconds before the third, and so on.

async function fetchWithRetry(url, options, maxRetries = 4) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(url, options);
    if (res.status !== 500) return res;

    const delay = Math.pow(2, attempt) * 1000;
    await new Promise((resolve) => setTimeout(resolve, delay));
  }
  throw new Error('Max retries reached — server error persisted');
}

If INTERNAL_ERROR responses persist after several retries, please contact the Noteboxd developer support team at https://developers.noteboxd.com with the request details and any error details from the response body.

Noteboxd does not bill you for failed requests. You will not be charged for calls that return a 4xx or 5xx response.

Get Started

Core Concepts

Guides

Help

Noteboxd API Error Codes and Troubleshooting Guide

Error response format

Error code reference

Handling errors in code

Retrying on 500 errors

​Error response format

​Error code reference

​Handling errors in code

​Retrying on 500 errors

Error response format

Error code reference

Handling errors in code

Retrying on 500 errors