Error Handling

General Error Response

When an API request fails, you'll receive a standardized error response object with the following structure:

{
  "code": "error_code",
  "message": "Human readable error message",
  "err": "Detailed error information"
}

HTTP Status Codes

The API uses standard HTTP status codes:

• 400 Bad Request - Invalid input parameters or validation failure
• 401 Unauthorized - Missing or invalid authentication
• 403 Forbidden - Valid authentication but insufficient permissions
• 404 Not Found - Requested resource doesn't exist
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server-side error

Error Codes Reference

Here's a comprehensive list of error codes you might encounter:

Authentication & Authorization Errors

Error Code	Description
missing_auth_header	The Authorization header is missing from the request
missing_api_key	No API key provided in the Authorization header
invalid_api	The provided API key is invalid
unauthorized	Authentication required or failed
forbidden	User lacks permission for the requested operation
invalid_token	The provided token is invalid
invalid_token_data	The token contains invalid data
invalid_refresh_token	The refresh token is invalid

Resource Not Found Errors

Error Code	Description
api_key_not_found	The specified API key doesn't exist
user_not_found	The requested user account was not found
workspace_not_found	The specified workspace doesn't exist
domain_not_found	The requested domain was not found
campaign_not_found	The specified campaign doesn't exist
url_not_found	The requested URL was not found
file_not_found	The specified file doesn't exist
tag_not_found	The requested tag was not found
qr_config_not_found	The specified QR configuration doesn't exist
plan_not_found	The requested subscription plan was not found

Validation Errors

Error Code	Description
invalid_request_body	The request body contains invalid data
invalid_campaign_id	Invalid campaign identifier provided
invalid_domain_id	Invalid domain identifier provided
invalid_url_id	Invalid URL identifier provided
invalid_file_id	Invalid file identifier provided
invalid_url_hash	Invalid URL hash provided
invalid_page	Invalid page number for pagination
invalid_page_size	Invalid page size for pagination
invalid_time_window	Invalid time window parameter
invalid_domain	Invalid domain name provided
invalid_expiration_date	Invalid expiration date format or value

Resource Status Errors

Error Code	Description
domain_not_active	The requested domain is currently inactive
user_not_active	The user account is currently inactive
url_not_active	The requested URL is currently inactive
expired_invitation	The invitation has expired

Limit Exceeded Errors

Error Code	Description
max_permanent_urls_reached	Reached the maximum allowed permanent URLs
max_agents_reached	Reached the maximum allowed agent users
max_custom_domains_reached	Reached the maximum allowed custom domains
max_tags_reached	Reached the maximum allowed tags
max_urls_reached	Reached the maximum allowed URLs
max_campaign_urls_reached	Reached the maximum allowed URLs in a campaign
to_many_requests	Rate limit exceeded

Feature Requirement Errors

Error Code	Description
feature_required_password_protection	Password protection feature required
feature_required_custom_domain	Custom domain feature required
feature_required_smart_urls	Smart URLs feature required
feature_required_campaigns	Campaigns feature required
feature_required_qr_configs	QR configurations feature required
feature_required_user_management	User management feature required
feature_required_api	API access feature required
feature_required_private_stats	Private statistics feature required
feature_required_pixel_retargeting	Pixel retargeting feature required
feature_required_url_preview	URL preview feature required

Other Errors

Error Code	Description
internal_error	An internal server error occurred
user_not_admin	Operation requires admin privileges
user_is_owner	Operation cannot be performed on workspace owner
url_validation_failed	URL validation check failed
https_needed	HTTPS protocol is required for this operation

Error Handling Example

try {
  const response = await fetch('https://api.joo.nz/v1/url', {
    headers: {
      'Authorization': 'YOUR_API_KEY'
    }
  });
  
  if (!response.ok) {
    const error = await response.json();
    console.error(`Error: ${error.code} - ${error.message}`);
    // Handle error appropriately
  }
} catch (err) {
  console.error('Request failed:', err);
}

Rate Limiting

The API implements rate limiting to ensure fair usage. When you exceed the rate limit, you'll receive a 429 Too Many Requests status code with the to_many_requests error code. We recommend implementing exponential backoff in your applications when encountering rate limit errors.