​
Error Response Format

All API errors follow a consistent format: 
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // Additional context (optional)
    }
  }
}

​
HTTP Status Codes

Status CodeDescription
200Success
201Created - Resource successfully created
400Bad Request - Invalid request parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
409Conflict - Resource already exists
422Unprocessable Entity - Validation failed
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Something went wrong

​
Error Codes Reference

​
Authentication Errors

​
UNAUTHORIZED
401
API key is missing from the request.
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key is required"
  }
}
​
INVALID_API_KEY
401
The provided API key is invalid or has been revoked.
{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked"
  }
}
​
FORBIDDEN
403
The API key doesn’t have permission for this action.
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Your API key does not have permission to perform this action"
  }
}

​
Validation Errors

​
VALIDATION_ERROR
422
Request parameters failed validation.
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "errors": [
        {
          "field": "url",
          "message": "URL is required and must be valid"
        }
      ]
    }
  }
}
​
INVALID_URL
400
The provided URL is not valid.
{
  "success": false,
  "error": {
    "code": "INVALID_URL",
    "message": "The URL format is invalid or the protocol is not supported"
  }
}

​
Resource Errors

​
NOT_FOUND
404
The requested resource doesn’t exist.
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Short URL not found"
  }
}
​
ALIAS_TAKEN
409
The custom alias is already in use.
{
  "success": false,
  "error": {
    "code": "ALIAS_TAKEN",
    "message": "This custom alias is already taken"
  }
}
​
ACCESS_DENIED
403
You don’t have access to this resource.
{
  "success": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "You do not have access to this resource"
  }
}

​
Rate Limit Errors

​
RATE_LIMIT_EXCEEDED
429
You’ve exceeded the rate limit for this endpoint.
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "details": {
      "limit": 100,
      "remaining": 0,
      "reset_at": "2024-01-15T12:00:00Z"
    }
  }
}

​
Server Errors

​
INTERNAL_ERROR
500
An unexpected error occurred on the server.
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Please try again later."
  }
}

​
Handling Errors

Here’s how to properly handle API errors in your code: 
async function makeApiRequest(endpoint, options) {
  try {
    const response = await fetch(`https://jmpy.me/api/v1${endpoint}`, options);
    const data = await response.json();
    
    if (!data.success) {
      switch (data.error.code) {
        case 'UNAUTHORIZED':
        case 'INVALID_API_KEY':
          throw new Error('Authentication failed. Check your API key.');
        case 'RATE_LIMIT_EXCEEDED':
          // Wait and retry
          const resetTime = data.error.details?.reset_at;
          throw new Error(`Rate limited. Retry after ${resetTime}`);
        case 'VALIDATION_ERROR':
          const errors = data.error.details?.errors || [];
          throw new Error(`Validation failed: ${errors.map(e => e.message).join(', ')}`);
        default:
          throw new Error(data.error.message);
      }
    }
    
    return data.data;
  } catch (error) {
    console.error('API Error:', error.message);
    throw error;
  }
}

​
Need Help?

Support

Contact our support team for help

API Status

Check if there are any ongoing issues

Rate Limits

Understand API rate limiting

Authentication

Set up API key authentication