Skip to content

errors.mdx

Latest commit

 

History

History
103 lines (83 loc) · 4.92 KB

errors.mdx

File metadata and controls

103 lines (83 loc) · 4.92 KB
Raw
title Noteboxd API Error Codes and Troubleshooting Guide
sidebarTitle Errors
description Reference for all Noteboxd API error codes, HTTP status codes, and recommended fixes to apply when your API requests return 4xx or 5xx responses.

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
401 WRONG_KEY_TYPE A hosted MCP or account key was used on the commercial API, or a portal API key was used on hosted MCP Send a portal API key to api.noteboxd.com. Send a hosted MCP key only to the hosted MCP endpoint
402 INSUFFICIENT_BALANCE The account's prepaid balance is less than the cost of this call 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 Call quota for the current window is exhausted Wait for Retry-After seconds, or until X-RateLimit-Reset
429 RECORD_CAP_EXCEEDED Distinct-record cap for the UTC day is exhausted. Re-reads of records already accessed today do not count; chart leaderboards do not count Wait until midnight UTC, or for Retry-After seconds
500 INTERNAL_ERROR Unexpected server error Retry with backoff; contact support if persistent

Creating or rotating a key in the developer portal can also fail before a secret is issued. Those responses use the same error envelope:

HTTP Status Code Meaning Fix
403 EMAIL_UNVERIFIED The account email is not verified Verify the email address, then create or rotate the key again
403 TERMS_NOT_ACCEPTED The account has not accepted the Terms Accept the Terms in the developer portal, then create or rotate the key again
4xx errors are not retryable without first fixing the underlying issue. Retry `429` (`RATE_LIMIT_EXCEEDED` or `RECORD_CAP_EXCEEDED`) only after `Retry-After`, and retry `500 INTERNAL_ERROR` with backoff.

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}`);
  }
}
On a `429`, the `Retry-After` header is the number of seconds to wait. `X-RateLimit-Reset` is the Unix timestamp when the current window resets. The code is either `RATE_LIMIT_EXCEEDED` or `RECORD_CAP_EXCEEDED`.

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.