Errors and limits
What Netzo returns when it refuses a request, how to fix or retry it, and how many requests it accepts.
Netzo refuses a request with the same error on every surface. The error says what happened and what to do, so a person or an agent fixes it without guessing.
What an error holds
| Field | Holds |
|---|---|
status | The HTTP status: 403, 409, 422… |
code | A stable code, such as rpc.RECORD_LOCKED. Use it in your code; do not compare the message. |
message | What happened, in the caller's language |
fix | The next step to fix it |
fields | The fields that caused the refusal, when they apply |
retryable | Whether the same request can work if you send it again |
The language follows the Accept-Language header (es or en), the same in the API, MCP and the CLI.
Kinds of error
| Status | Means | Common codes | What to do |
|---|---|---|---|
401 | The credential is missing or not valid | UNAUTHENTICATED | Send a valid credential. See Authentication |
403 | The credential does not have the permission | FORBIDDEN, FIELD_FORBIDDEN, APPROVAL_REQUIRED | Ask for the permission, or the approval. Check first with can |
404 | The record does not exist or you cannot see it | NOT_FOUND | Check the id and the place |
409 | The change conflicts with the state or a rule | INVARIANT_VIOLATED, RECORD_LOCKED, IDENTIFIER_NOT_UNIQUE, CONCURRENT_UPDATE | Read fix. See Rules and integrity |
412 | An approval is missing or still pending | APPROVAL_PENDING, APPROVAL_REQUEST_MISSING | Wait for the approval. See Access |
422 | The input is not valid | — | Fix the fields in fields |
429 | Too many requests | TOO_MANY_REQUESTS | Wait the time in Retry-After |
A rule of a table has its own code, and its message already says how to fix it, for example "The fiscal period is closed".
Retries
Retry only when retryable is true. CONCURRENT_UPDATE means another request changed the record first: read it again and make the change again. Any other error repeats until you fix its cause.
To not create a record twice when you retry, find it first by its business key. See API.
By surface
| Surface | How the error arrives |
|---|---|
| API | The HTTP status, with the error in the JSON body |
| MCP | A tool error with the message, fix and the fields |
| CLI | The error on standard error and a stable exit code. See CLI |
| App | A notice with the message and the fix, next to the field when it applies |
Limits
| Limit | Value |
|---|---|
| Requests to the API and MCP | 1,200 per minute per credential: each API key, each person with OAuth and each signed-in person has its own limit |
| Life of an API key | 90 days if you choose no other date; 365 at most |
| Webhook delivery | 10 seconds per try, up to 3 retries. See Webhooks |
A request over the limit gets 429 and the Retry-After header with the seconds left.