API Error Reference

Understanding and handling AdMorph API errors

Error Response Format

All API errors follow a consistent JSON structure to make error handling straightforward and predictable. 

{
  "error": "Error Type",
  "message": "Human-readable error description",
  "details": {
    // Optional additional context
  }
}

HTTP Status Codes

AdMorph API uses standard HTTP status codes to indicate the success or failure of requests:

Client Errors (4xx)

400 Bad Request
The request was invalid or cannot be processed. This usually indicates missing required parameters, invalid parameter values, or malformed JSON. 
{
  "error": "Bad Request",
  "message": "Prompt is required"
}

Common Causes:

  • Missing required fields (e.g., prompt parameter)
  • Invalid parameter values (e.g., invalid duration or orientation)
  • Malformed JSON in request body
  • Invalid file format for image uploads
  • File size exceeds limits

How to Fix:

  • Check the error message for specific details about what's wrong
  • Verify all required parameters are included
  • Ensure parameter values match the API specification
  • Validate your JSON before sending
401 Unauthorized
Authentication failed. Your API key is either missing, invalid, or has been revoked. 
{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Common Causes:

  • Missing X-API-Key header
  • Invalid or malformed API key
  • API key has been revoked
  • API key format is incorrect (should start with adm_live_)

How to Fix:

  • Ensure the X-API-Key header is present in your request
  • Verify your API key is correct (check for typos)
  • If the key was revoked, create a new one in your dashboard settings
  • Make sure you're using the full API key value
402 Insufficient Credits
Your account doesn't have enough credits to complete this request. 
{
  "error": "Insufficient Credits",
  "message": "Not enough credits. Required: 2, Available: 1",
  "details": {
    "required": 2,
    "available": 1
  }
}

Common Causes:

  • Account credit balance is too low
  • Multiple simultaneous requests depleted credits
  • Credits reserved by pending submissions

How to Fix:

  • Check your credit balance: GET /api/v1/user/credits
  • Purchase more credits from your dashboard
  • Wait for pending submissions to complete (failed submissions return credits)
404 Not Found
The requested resource doesn't exist. This typically occurs when using an invalid submission ID or accessing a non-existent endpoint. 
{
  "error": "Not Found",
  "message": "Submission not found"
}

Common Causes:

  • Invalid submission ID
  • Trying to access another user's submission
  • Incorrect API endpoint URL
  • Typo in the submission ID

How to Fix:

  • Verify the submission ID is correct
  • Check that you're using the right endpoint URL
  • Ensure you're only accessing your own submissions
  • List your submissions to find valid IDs: GET /api/v1/submissions
429 Too Many Requests
You've exceeded the rate limit for API requests. The API allows 100 requests per hour per API key. 
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Maximum 100 requests per hour.",
  "retryAfter": 3600
}

Common Causes:

  • Making too many requests in a short period
  • Polling endpoints too frequently
  • Not implementing proper backoff logic

How to Fix:

  • Wait for the rate limit to reset (check X-RateLimit-Reset header)
  • Implement exponential backoff for retries
  • Use webhooks instead of polling for status updates
  • Contact support if you need higher rate limits

Server Errors (5xx)

500 Internal Server Error
An unexpected error occurred on the server. This is rare and usually temporary. 
{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred. Please try again."
}

Common Causes:

  • Temporary server issues
  • Database connection problems
  • Unexpected edge cases in request processing

How to Fix:

  • Retry the request after a short delay
  • Implement exponential backoff for retries
  • If the error persists, contact support with the request details
  • Check our status page for known issues
503 Service Unavailable
The service is temporarily unavailable, usually due to maintenance or high load. 
{
  "error": "Service Unavailable",
  "message": "Service temporarily unavailable. Please try again later."
}

Common Causes:

  • Scheduled maintenance
  • System overload
  • Temporary infrastructure issues

How to Fix:

  • Wait and retry after a few minutes
  • Check for maintenance announcements
  • Implement retry logic with exponential backoff

Error Handling Best Practices

1. Always Check Status Codes

// Python example
response = requests.post(url, headers=headers, json=data)

if response.status_code == 200:
    # Success
    submission = response.json()['submission']
elif response.status_code == 402:
    # Insufficient credits
    print("Not enough credits. Please purchase more.")
elif response.status_code == 429:
    # Rate limited
    retry_after = response.json().get('retryAfter', 3600)
    time.sleep(retry_after)
else:
    # Other error
    error = response.json()
    print(f"Error: {error['message']}")

2. Implement Retry Logic

// Node.js example with exponential backoff
async function makeRequestWithRetry(url, options, maxRetries = 3) {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
        try {
            const response = await axios.post(url, options);
            return response.data;
        } catch (error) {
            const status = error.response?.status;

            // Don't retry client errors (except 429)
            if (status >= 400 && status < 500 && status !== 429) {
                throw error;
            }

            // Last attempt failed
            if (attempt === maxRetries - 1) {
                throw error;
            }

            // Exponential backoff: 1s, 2s, 4s
            const delay = Math.pow(2, attempt) * 1000;
            await new Promise(resolve => setTimeout(resolve, delay));
        }
    }
}

3. Use Webhooks to Avoid Polling

Instead of repeatedly polling for status updates (which can trigger rate limits), configure a webhook to receive notifications when submissions complete.

Learn more about webhooks →

4. Handle Credits Gracefully

// Check credits before creating submission
const creditsResponse = await fetch(
    'https://admorph.net/api/v1/user/credits',
    { headers: { 'X-API-Key': apiKey } }
);

const { credits } = await creditsResponse.json();

if (credits < requiredCredits) {
    console.log(`Insufficient credits. You have ${credits}, need ${requiredCredits}`);
    // Redirect user to purchase credits
} else {
    // Proceed with submission
}

5. Log Errors for Debugging

Always log error responses with enough context to debug issues:

Getting Help

If you encounter an error you can't resolve:

When contacting support, please include:

← Webhooks Getting Started →