UniLink API Error Codes (Understand and Handle API Errors)

Every error the UniLink API returns has a predictable structure and a specific HTTP status code — knowing what each one means gets your integration back on track fast.

The UniLink API returns structured error responses that make it straightforward to distinguish between a misconfigured request, an authorization problem, and a server-side issue. Rather than guessing from status codes alone, every error body tells you exactly what went wrong in both machine-readable and human-readable form. Learning the error taxonomy upfront saves hours of debugging time when building and maintaining integrations.

What API Error Responses Look Like

Every error response from the UniLink API has the same JSON envelope. The error field is a snake_case string code identifying the error type — for example, validation_error, unauthorized, or rate_limit_exceeded. The message field is a human-readable sentence explaining what went wrong. The optional details field contains additional context — for validation errors it is an object mapping field names to arrays of error messages; for other errors it may contain a retry_after timestamp or a field name. The HTTP status code and the error string together give you everything you need to decide how to respond programmatically.

The error taxonomy divides into two groups based on who is responsible. 4xx status codes indicate a client error — your request was malformed, your credentials were wrong, or you asked for something that does not exist. These errors do not resolve by retrying the same request. You need to fix the request before trying again. 5xx status codes indicate a server error — UniLink's infrastructure encountered an unexpected problem. These are temporary by nature and should be retried with exponential backoff after a brief delay.

Validation errors (400 and 422) deserve special attention because they carry the most detail. A 400 Bad Request typically means a required field is missing or a value is the wrong type. A 422 Unprocessable Entity means the request was structurally valid JSON but the values violated a business rule — for example, creating a page with a slug that exceeds the maximum length or a price that is negative. The details object in validation error responses maps each invalid field to a list of human-readable messages, making it straightforward to surface exactly what needs to be corrected.

How to Get Started

1. Add a global error handler to your HTTP client that reads both the HTTP status code and the JSON response body. Do not rely on status codes alone — the error field gives you the specific error type for routing to the right handler.
2. Log the full error response body (status, error, message, details) during development. This context is invaluable for debugging — the message field often tells you exactly what is wrong without needing to consult the docs.
3. Implement separate handling for 4xx and 5xx responses. For 4xx: surface the error to the user or halt and fix the request. For 5xx: retry with exponential backoff starting at 1 second, up to 3–5 retries.
4. Add special handling for 429 responses — read the retry_after value from the response body and sleep precisely until that timestamp before retrying, rather than using a fixed delay.
5. Test your error handling by deliberately triggering each error type: send a request without an Authorization header (401), request a non-existent resource (404), send a POST with a missing required field (400).

How to Handle Each Error Type

1. 400 Bad Request: A required parameter is missing or has the wrong type. Read details to find which field is invalid. Fix the request body or query string and retry immediately — this is not a transient error.
2. 401 Unauthorized: The Authorization header is missing, malformed, or the token has been revoked. Check that the header is present and formatted as Bearer YOUR_KEY. If the key was revoked, generate a new one in Settings → API.
3. 403 Forbidden: The token is valid but lacks the scope for this operation — for example, a read-only key trying to POST. Generate a new key with the required scope (write or admin) and update your configuration.
4. 404 Not Found: The requested resource does not exist or has been deleted. Check the ID or slug in your URL. If this is unexpected, the resource may have been archived — check the dashboard to confirm.
5. 409 Conflict / 422 Unprocessable Entity / 429 Rate Limited / 500 Server Error: For 409 (duplicate), adjust your payload to use a unique identifier. For 422, read details for the specific rule violation. For 429, wait until retry_after. For 500, retry with exponential backoff — it is a transient server issue.

Key Settings

Get the Most Out Of Error Handling

Build your error handler as a central function rather than duplicating try/catch logic across every API call. Your central handler should accept the HTTP response, classify it by status code, extract the error and message fields, and either throw a typed exception your business logic can catch, or return a typed error object. This pattern means you fix error handling once and every part of your integration benefits immediately.

Distinguish between retryable and non-retryable errors at the classification level. Retryable: 429, 500, 502, 503, 504, and network timeouts. Non-retryable: 400, 401, 403, 404, 409, 422. Writing this distinction into your error classifier prevents a common bug where validation errors are retried in a loop until rate limits are exhausted — often the symptom that surfaces is a 429 error, misleadingly suggesting a rate limit problem when the root cause is a bad request.

Surface 401 and 403 errors to your operations team immediately rather than silently retrying or swallowing them. A 401 usually means your API key was accidentally revoked or the environment variable is missing from a deployment. A 403 usually means the key's scope was set incorrectly. Both are configuration problems that require human intervention — automated retries will not resolve them, but an alert will get them fixed quickly.

Use the error code field (not just the HTTP status) to drive your error UI messages. The error field distinguishes between multiple scenarios that share the same HTTP status — for example, a 400 response might have an error of missing_required_field, invalid_format, or value_out_of_range. Routing on the specific error code lets you show contextually accurate messages rather than a generic "something went wrong" for every 400.

Troubleshooting

• All UniLink API errors return JSON with error (code), message (text), and optional details.
• 4xx errors are client-side problems — fix the request. 5xx errors are server-side — retry with backoff.
• Never auto-retry 4xx errors — they will fail every time until the request itself is corrected.
• Use the error code field (not just the HTTP status) to drive precise error handling and user-facing messages.
• 401 means bad/missing auth; 403 means wrong scope; 429 means rate limited — each requires a different fix.