Rate limits and errors

Error codes, retry guidance, and the customer-safe error glossary.

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:

Error Code	Safe Message
`CONVERSION_REPORTING_BACKEND_UNAVAILABLE`	Conversion reporting is temporarily unavailable. Please try again later or contact support.
`EXPORTS_UNAVAILABLE`	Exports are temporarily unavailable. Please try again later or contact support.
`EXPORT_JOB_FAILED`	Export generation failed. Retry with a smaller range or narrower scope, or contact support if this continues.
`DOMAIN_ACCESS_CONFIGURATION_UNAVAILABLE`	Domain access settings are temporarily unavailable. Please try again later or contact support.
`ORGANIZATION_WORKSPACE_MANAGEMENT_UNAVAILABLE`	Organization workspace management is temporarily unavailable. Please try again later or contact support.
`MEMBER_MANAGEMENT_UPDATE_FAILED`	Failed to apply the member change. Please try again later or contact support.
`LINK_MANAGEMENT_UPDATE_FAILED`	Failed to update the link settings. Please try again later or contact support.
`WORKSPACE_RESOURCE_UNAVAILABLE`	Workspace resources are temporarily unavailable. Please try again later or contact support.
`WEBHOOK_DELIVERY_FAILED`	Webhook delivery failed. Review the endpoint and try again, or contact support if this continues.
`WEBHOOK_ENDPOINT_DISABLED`	Webhook delivery is paused because the endpoint is disabled.
`FILE_UPLOAD_FAILED`	The upload could not be completed. Please try again later or contact support.
`GENERIC_TEMPORARY_UNAVAILABLE`	This feature is temporarily unavailable. Please try again later or contact support.

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.