# NEXUS AI Errors and Rate Limits

How NEXUS AI reports failures, and when an agent should retry.

## Error shapes

GPT-compatible API (`https://mcp.nexusai.run/api/gpt`):

```json
{ "error": "Deployment not found", "code": "DEPLOYMENT_NOT_FOUND", "details": {} }
```

Platform API (`https://api.nexusai.run/api`):

```json
{ "status": "error", "message": "Query blocked: Statement type not permitted" }
```

MCP tools return the message as tool output with `isError` set.

## GPT API error codes

| Code | Meaning | Retry? |
|---|---|---|
| `INVALID_TOKEN` | Token missing, malformed, or revoked | No. Fix the token |
| `TOKEN_EXPIRED` | Token past `expiresAt` | No. Issue a new token |
| `INSUFFICIENT_SCOPE` | Token lacks the required scope | No. Ask for a token with the scope |
| `RATE_LIMIT_EXCEEDED` | Too many requests | Yes, after `Retry-After` |
| `DEPLOYMENT_NOT_FOUND` | Unknown ID, or not in your organization | No |
| `PROJECT_NOT_FOUND` | Unknown project ID | No |
| `INVALID_REQUEST` | Body failed validation | No. Fix the request |
| `DEPLOYMENT_FAILED` | Build or start failed | After fixing the cause. Read the logs |
| `DUPLICATE_REQUEST` | Same `requestId` already used | No. The first request is in progress |
| `QUOTA_EXCEEDED` | Plan limit reached | No. See [Plans and limits](/docs/plans.md) |
| `PROVIDER_NOT_ALLOWED` | Provider not available on the plan | No |
| `INTERNAL_ERROR` | Server error | Yes, with backoff |

## HTTP status codes

- `400`: invalid request, or blocked by a safety check such as the [SQL rules](/docs/sql-safety.md).
- `401`: missing or invalid token.
- `403`: the token or user lacks the scope or permission.
- `404`: not found, or belongs to another organization.
- `429`: rate limited.
- `5xx`: server error. Retry with exponential backoff.

## Rate limits

| Surface | Limit |
|---|---|
| GPT API deploy and delete | 20 per hour per organization |
| GPT API reads (status, logs, lists) | 60 per minute per organization |
| MCP | 300 requests per 5 minutes per token |
| Platform API | 100 requests per 15 minutes per client |
| Deployment creation | 10 per 15 minutes per user |
| Custom domain verification | 3 per 5 minutes per user |

GPT API responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`, and a `429` includes `Retry-After` in seconds.

## Idempotency

`POST /deploy` and `POST /deploy/source` accept a `requestId`. Reusing it returns `DUPLICATE_REQUEST` instead of starting a second deployment, so it is safe to retry after a network error.

## Related resources

- [API](/docs/api.md)
- [OpenAPI](/openapi.json)