Rate limits and errors

Prerequisites

When designing your application to handle Nimriz errors, you should:

• Implement robust error handling capable of distinguishing between client errors (4xx) and server errors (5xx).
• Incorporate exponential backoff for rate-limited requests.
• Log error code and support_reference fields to assist with troubleshooting.

Error handling guidelines

• Treat 4xx responses as a signal to fix inputs (e.g., validate the slug, destination URL, or authentication credentials) rather than retrying immediately.
• Treat 429 Too Many Requests as retryable using an exponential backoff strategy.
• For automation and integrations, ensure link creation calls are idempotent so that retries do not inadvertently create duplicates.

Common causes of failure

• Invalid destination scheme: Only https:// (and optionally http:// if policy allows) are accepted.
• Reserved slug: System paths (e.g., api, admin, _health) are blocked on Nimriz domains. Slugs below the minimum required length are also treated as reserved.
• Quota or rate limit exceeded: Requests may be throttled or blocked if you exceed your plan's limits or hit abuse thresholds.

Customer-Safe Error Glossary

When internal fallbacks or infrastructure errors occur, Nimriz returns safe, standardized error messages. The following codes are commonly encountered:

API Response Contract

When an error occurs, Nimriz APIs return a structured JSON response containing the safe message and a support reference to help with debugging.

{
  "error": "Conversion reporting is temporarily unavailable. Please try again later or contact support.",
  "code": "CONVERSION_REPORTING_BACKEND_UNAVAILABLE",
  "support_reference": "nimerr_12345678-1234-1234-1234-123456789abc",
  "retryable": true
}

Troubleshooting

• Repeated 429 Errors: If you are consistently hitting rate limits, check your integration's retry logic to ensure it includes exponential backoff. Consider bulk operations (POST /api/shorten/bulk) instead of individual rapid requests.
• Unclear Failures: Always capture and log the code and support_reference from the JSON response. If you must contact support, providing the support_reference allows our team to quickly locate the specific failure.
• UI Fallbacks: If the dashboard displays an error banner with a reference string, taking a screenshot or copying the reference string will speed up support resolution.