Error Handling

All NeuralRepo API errors return a JSON object with an error field describing what went wrong.

Error Response Format

{
  "error": "A human-readable error message"
}

The error field is always a string. The HTTP status code indicates the category of error.

Status Codes

400 Bad Request

The request body or query parameters failed validation.

{
  "error": "Title must be between 1 and 200 characters"
}

Common causes:

• Missing required fields (e.g., title on idea creation)
• Field exceeds length limit (body > 50,000 chars, tags > 20 items)
• Invalid format (e.g., color not matching #rrggbb, invalid URL)
• Invalid query parameter values

401 Unauthorized

Authentication is missing or invalid.

{
  "error": "Invalid API key"
}

Common causes:

• No Authorization or X-API-Key header provided
• Expired session token
• Revoked or malformed API key

403 Forbidden

The request is authenticated but not allowed.

{
  "error": "Plan limit exceeded: upgrade to create more ideas"
}

Common causes:

• Plan limits reached (e.g., free plan idea cap)
• No BYOK key configured when calling /ideas/:id/develop
• Insufficient scope on the API key

404 Not Found

The requested resource does not exist.

{
  "error": "Idea not found"
}

Common causes:

• Invalid or non-existent ID in the URL path
• Resource belongs to another user
• Archived resource (in some contexts)

409 Conflict

The request conflicts with the current state of a resource.

{
  "error": "Relation would create a cycle"
}

Common causes:

• Creating a relation that would form a cycle in the graph (see ?force=true in Relations)
• Merging an idea that is already archived
• Creating a tag with a name that already exists
• Duplicate detection conflict during idea creation

429 Too Many Requests

You have exceeded the rate limit. See Rate Limits for details.

{
  "error": "Rate limit exceeded"
}

Wait for the time indicated by the Retry-After header before retrying.

500 Internal Server Error

An unexpected error occurred on the server.

{
  "error": "Internal server error"
}

If this persists, contact support. These errors are logged and monitored automatically.

Handling Errors in Code

JavaScript

const res = await fetch("https://neuralrepo.com/api/v1/ideas", {
  method: "POST",
  headers: {
    "X-API-Key": "nrp_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ title: "" }),
});

if (!res.ok) {
  const { error } = await res.json();
  switch (res.status) {
    case 400:
      console.error("Validation error:", error);
      break;
    case 401:
      console.error("Auth error — check your API key");
      break;
    case 429:
      const retryAfter = res.headers.get("Retry-After");
      console.error(`Rate limited. Retry after ${retryAfter}s`);
      break;
    default:
      console.error(`Error ${res.status}:`, error);
  }
}

curl

# curl shows the HTTP status with -w and the body together
curl -s -w "\nHTTP Status: %{http_code}\n" \
  -X POST https://neuralrepo.com/api/v1/ideas \
  -H "X-API-Key: nrp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": ""}'

Summary Table

Status	Name	Retryable	Description
400	Bad Request	No	Fix the request and resend
401	Unauthorized	No	Check authentication credentials
403	Forbidden	No	Check plan limits or permissions
404	Not Found	No	Verify the resource ID
409	Conflict	No	Resolve the conflict (e.g., use ?force=true)
429	Too Many Requests	Yes	Wait and retry with backoff
500	Internal Server Error	Yes	Retry with exponential backoff