Errors

Every error response from NullSpend — both the proxy and the dashboard API — uses the same format:

{
  "error": {
    "code": "budget_exceeded",
    "message": "Request blocked: estimated cost exceeds remaining budget",
    "details": null
  }
}

• code — Machine-readable error identifier. Use this for programmatic handling.
• message — Human-readable explanation.
• details — Additional context (object or null). Present on validation errors, session limits, and velocity limits.

Proxy Errors

These errors are returned by the NullSpend proxy (proxy.nullspend.dev).

Authentication

Budget Enforcement

Per-Customer Budgets (/v1/bind, /v1/gate, /v1/customers/:id/unit-economics)

See Unit Economics API for the full request/response shapes and the Per-Customer Budgets guide for the conceptual model. | loop_detected | 429 | Repeated identical or similar prompts exceeded the loop-detection threshold within the sliding window | Inspect agent logic for retry loops. Adjust thresholds in budget settings, or set loop_max_calls to disable. Retry-After returns the recommended cooldown | | plan_limit_exceeded | 429 | Org exceeded its NullSpend plan-tier governed-request cap (Free tier hard-blocks today) | Upgrade via the upgrade_url returned in the body, or wait for the next period reset. Top-level error.upgrade_url and error.self_host_url are set on this denial | | budget_unavailable | 503 | Budget enforcement service is temporarily unavailable | Retry after a brief delay. The proxy fails closed — requests are blocked, not passed through |

Policy (Mandates)

Request Validation

Rate Limiting

Rate limit responses include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After headers. See the headers reference. For the full rate limiting reference, see Rate Limits.

Upstream & Server

Dashboard API Errors

These errors are returned by the NullSpend dashboard API (nullspend.dev/api/).

Validation

Validation error details include an issues array:

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "details": {
      "issues": [
        { "path": ["amount"], "message": "Expected number, received string" }
      ]
    }
  }
}

Resources

HITL Actions

Rate Limiting

Note: The proxy uses rate_limited while the dashboard API uses rate_limit_exceeded. Handle both codes if your application calls both services.

Authentication & Authorization

Server

HTTP Status Code Summary

Handling Errors Programmatically

const response = await fetch("https://proxy.nullspend.dev/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.OPENAI_API_KEY}`,
    "X-NullSpend-Key": process.env.NULLSPEND_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ model: "gpt-4o", messages: [{ role: "user", content: "Hello" }] }),
});

if (!response.ok) {
  const { error } = await response.json();
  switch (error.code) {
    case "budget_exceeded":
      // Notify the user, queue for later, or request budget increase
      break;
    case "velocity_exceeded":
      // Back off and retry after Retry-After seconds
      const retryAfter = response.headers.get("Retry-After");
      break;
    case "rate_limited":
      // Reduce request rate
      break;
    case "loop_detected":
      // Stop the agent loop — repeated calls were blocked
      break;
    case "plan_limit_exceeded":
      // Surface the upgrade CTA
      console.log(`Plan cap hit. Upgrade: ${error.upgrade_url}`);
      break;
    case "mandate_violation":
      // Switch to an allowed model/provider
      console.log(`Allowed: ${error.details?.allowed?.join(", ")}`);
      break;
    default:
      console.error(`NullSpend error: ${error.code} — ${error.message}`);
  }
}

API Reference

• API Overview — authentication, pagination, ID formats
• Cost Events API — ingest, list, and analyze cost events
• API Keys API — create, list, revoke keys, and introspect identity
• Budgets API — create, manage, and query budgets
• Webhooks API — manage webhook endpoints and deliveries
• Actions API — human-in-the-loop approval workflows