Error Codes Admin
The Nucleus API uses standard HTTP status codes. All error responses include a JSON body with an error field.
Response Format
{
"error": "Description of what went wrong"
}Status Codes
| Code | Meaning | Common Cause |
|---|---|---|
| 200 | OK | Request succeeded |
| 400 | Bad Request | Missing or invalid parameters (e.g., bad date format, missing required field) |
| 401 | Unauthorized | Missing or invalid token. Re-authenticate and try again. |
| 403 | Forbidden | Valid token but insufficient permissions. Your role or API key does not have access to this resource. |
| 404 | Not Found | The endpoint or resource does not exist. Check the URL. |
| 429 | Rate Limited | You exceeded 1,000 requests per hour. Wait before retrying. |
| 500 | Server Error | Something went wrong on the server. Retry after a short delay. If persistent, contact support. |
Handling Errors
400 — Bad Request
Check your request parameters. Common issues:
- Date format should be
YYYY-MM-DD. - Required fields are missing.
per_pageexceeds the maximum (10,000).
401 — Unauthorized
Your token is missing, malformed, or expired. If using a JWT, log in again to get a fresh token. If using an API key, verify it has not been deleted.
429 — Rate Limited
Back off and retry. The rate limit resets hourly. For bulk data extraction, use the bulk export endpoint instead of paginating through events.
500 — Server Error
Retry after 30 seconds. If the error persists for more than a few minutes, the issue is on the server side. Contact your Nucleus admin.
Include the full error response when reporting issues. The error message often contains enough detail to diagnose the problem.