Errors and Limits

Noorle has three request surfaces, and they do not share an error format. The management API returns a JSON error body with an HTTP status. The MCP and A2A gateways speak JSON-RPC 2.0 and carry failures in the response envelope.

Management API errors

Errors from api.noorle.com serialize as a flat object — there is no nested error wrapper.

{
  "timestamp": "2026-08-04T10:30:45.123456Z",
  "category": "Authorization",
  "message": "Token is not valid"
}

Field	Always present	Meaning
`timestamp`	yes	When the error was generated (RFC 3339, UTC)
`category`	yes	The error class, which determines the HTTP status
`message`	on most errors	Human-readable description
`code`	rarely	Reserved; omitted when unset
`details`	validation errors only	Per-field validation failures

Validation errors carry details instead of message, keyed by field name.

404 responses have no body. When the category is NotFound, the API returns the bare status with no JSON payload. Do not parse the body of a 404.

Category to status code

Every management API status comes from one of these eleven categories.

`category`	HTTP status
`Malformed`	400 Bad Request
`Authentication`	401 Unauthorized
`Authorization`	403 Forbidden
`NotFound`	404 Not Found (empty body)
`Timeout`	408 Request Timeout
`Conflict`	409 Conflict
`Validation`	422 Unprocessable Entity
`RateLimit`	429 Too Many Requests
`Internal`	500 Internal Server Error
`PartnerSystems`	502 Bad Gateway
`ServiceUnavailable`	503 Service Unavailable

Successful responses return 200 OK. The only endpoint that returns 204 No Content is the internal billing cache-invalidation callback. Nothing on the public management surface returns 201 Created. 413 Payload Too Large is returned by the plugin upload endpoint when the request body exceeds its limit — see Upload Plugin.

What each category means for you

403 Forbidden — credentials and permissions

The management API returns 403 for credential problems as well as permission problems: a missing Authorization header, a malformed token, an expired token, a revoked API key, and an insufficiently privileged caller all produce category: "Authorization".A 403 therefore does not tell you whether to re-authenticate or to ask for access. Check the message field, which distinguishes them ("Authorization header is missing" vs. "Account access denied").Across the platform, an authority denial is 403 and a resource that exists outside your account’s tenancy floor is 404 — a denied caller cannot probe for the existence of another account’s resources.

404 Not Found — no body

Returned when the resource does not exist, or exists outside your account. The response body is empty; there is nothing to parse.

422 Unprocessable Entity — validation

Field-level validation failed. message is absent; read details, which maps each rejected field to its validation messages.

503 Service Unavailable — dependency down

A dependency is temporarily unavailable. This is deliberately distinct from 500 so clients can retry without treating it as an application bug.

JSON-RPC errors (MCP and A2A)

Both gateway surfaces return JSON-RPC 2.0 errors. The A2A gateway returns HTTP 200 with the error in the envelope — the HTTP status is not the signal.

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

Standard codes

Code	Meaning
-32700	Parse error — invalid JSON
-32600	Invalid request
-32601	Method not found
-32602	Invalid params
-32603	Internal error

Noorle server-defined codes

Both sit in the JSON-RPC server-error range (-32000 to -32099).

Code	Surface	Meaning
-32029	MCP gateway	Rate limit exhausted. Retryable — back off and retry.
-32050	Agent runtime	An autonomy gate paused the call and is waiting on a human decision. Not an error to retry blindly.

A rate-limit error carries a structured data payload:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32029,
    "message": "Rate limit exceeded for gateway ...",
    "data": {
      "code": "RATE_LIMIT_EXCEEDED",
      "limit": 600,
      "window_secs": 60
    }
  }
}

-32029 is deliberately not -32600 Invalid request: many clients treat Invalid request as non-retryable, and a rate limit is retryable by contract.

Limits and quotas

Noorle enforces two kinds of limit, and it helps to keep them apart:

Request-rate limits on a handful of specific endpoints, listed below.
Economic and object-count quotas per account — how many skills you can keep, how many times your triggers may fire in a day, how much attachment storage you consume in a month.

There is no account-wide request-rate quota. Noorle does not meter total requests per account across the platform. The rate limits that exist are per-endpoint and are named individually here; everything else is bounded by the account quotas instead.

No response carries X-RateLimit-Limit, X-RateLimit-Remaining, or X-RateLimit-Reset. Noorle does not emit those headers on any surface. Do not key backoff logic on them. The one rate-limit response header Noorle emits is Retry-After: 60, on the MCP gateway handshake 429.

Request-rate limits

Fixed-window counters — no burst allowance, no token bucket.

Limit	Value	Window	Keyed on	Exceeded response
MCP gateway requests	600 / minute	60 s, fixed	Gateway × caller principal (anonymous callers key on peer IP)	JSON-RPC `-32029`
MCP gateway handshake (`initialize`)	60 / minute	60 s, fixed	Gateway × caller principal (anonymous callers key on peer IP)	HTTP 429 with `Retry-After: 60`
MCP gateway token endpoint	10 / minute	60 s, fixed	Client IP × gateway host	HTTP 429
MCP gateway refresh-token grant	5 / minute	60 s, fixed	Client IP × `client_id`	HTTP 429
Outbound SMS	100 / hour	60 min	Sending phone number	Message not sent

Two properties worth designing around:

tools/call and tools/list share one budget. The 600/minute limit covers the authenticated request path, not each method separately. initialize and ping sit outside it — that is why the handshake has its own limiter.
The MCP limiters favor availability. If the counter’s backing store is unreachable, requests are allowed through rather than rejected.

The last two rows are worth reading carefully. The token-endpoint limits belong to each MCP gateway’s own OAuth server — they are keyed on the gateway host and apply at mcp-{handle}.noorle.com/oauth/token. The management API’s device flow at api.noorle.com/oauth/token is not rate limited. The agent (A2A) gateway has no rate limiting.

Account quotas

These are the ceilings that actually bound a busy account.

Quota	Limit	Scope	Resets
Trigger fires	500 / day	Account	Midnight UTC
Trigger fires	100 / day	Agent	Midnight UTC
Attachments	10,000 / month	Account	Calendar month
Attachment storage	1 GiB / month	Account	Calendar month
Attachments per message	10	Message	—
Attachment file size	20 MiB	File	—
Skills	1,000	Account	—
Workflows	1,000	Account	—

A trigger firing consumes both budgets at once — the agent’s and the account’s — and is rejected if either is exhausted, so one busy agent cannot drain the account’s whole daily allowance on its own. Attachments beyond the per-message cap, or arriving after a monthly ceiling is reached, are not processed; the message itself still goes through. Beyond these, several surfaces enforce their own size and time caps — request body size, plugin archive size, tool execution timeouts. Those are documented with the endpoints that enforce them.

Handling failures

Retry on 429, 500, 502, 503, 504, and JSON-RPC -32029. Do not retry 400, 403, 404, or 422 — the request will fail identically.

import time
import random
import requests

RETRYABLE = {429, 500, 502, 503, 504}

def call_with_retry(url, headers, max_attempts=4):
    for attempt in range(max_attempts):
        resp = requests.get(url, headers=headers, timeout=30)
        if resp.status_code not in RETRYABLE:
            return resp
        if attempt == max_attempts - 1:
            resp.raise_for_status()
        # Full jitter. No rate-limit headers exist to read a reset time from.
        time.sleep(random.uniform(0, 2 ** attempt))

For the MCP gateway, inspect the JSON-RPC error code rather than the HTTP status — a rate-limited tools/call arrives as HTTP 200 carrying -32029.

const body = await response.json();
if (body.error?.code === -32029) {
  const { limit, window_secs } = body.error.data ?? {};
  // Back off for at least window_secs before retrying.
}

Overview

REST API

MCP Protocol

A2A Protocol

Noorle CLI

Errors and Limits

Management API errors

Category to status code

What each category means for you

JSON-RPC errors (MCP and A2A)

Standard codes

Noorle server-defined codes

Limits and quotas

Request-rate limits

Account quotas

Handling failures

Next steps

​Management API errors

​Category to status code

​What each category means for you

​JSON-RPC errors (MCP and A2A)

​Standard codes

​Noorle server-defined codes

​Limits and quotas

​Request-rate limits

​Account quotas

​Handling failures

​Next steps

Management API errors

Category to status code

What each category means for you

JSON-RPC errors (MCP and A2A)

Standard codes

Noorle server-defined codes

Limits and quotas

Request-rate limits

Account quotas

Handling failures

Next steps