Skip to main content

​
Error Handling

The Garmint API uses standard HTTP status codes and returns consistent JSON error responses.

​
Error Response Format

All errors follow this structure: 
{
  "error": {
    "code": "error_code",
    "message": "Human-readable description",
    "details": { ... }
  }
}
FieldTypeDescription
codestringMachine-readable error code
messagestringHuman-readable description
detailsobjectAdditional context (optional)

​
Error Codes

​
Authentication Errors

CodeStatusDescription
unauthorized401Missing or invalid API key
forbidden403Key lacks permission for this action
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key. Provide a valid key via Authorization header."
  }
}

​
Request Errors

CodeStatusDescription
invalid_request400Malformed request body or parameters
not_found404Requested resource doesn’t exist
{
  "error": {
    "code": "invalid_request",
    "message": "The request body is invalid.",
    "details": {
      "reason": [
        { "path": ["designUrl"], "message": "Required" }
      ]
    }
  }
}

​
Rate & Usage Errors

CodeStatusDescription
rate_limited429Too many requests
insufficient_tokens402Not enough tokens for operation
{
  "error": {
    "code": "insufficient_tokens",
    "message": "You don't have enough tokens for this operation.",
    "details": {
      "required": 1,
      "available": 0
    }
  }
}

​
Server Errors

CodeStatusDescription
internal_error500Unexpected server error
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred. Please try again."
  }
}

​
HTTP Status Codes

StatusMeaning
200Success
201Created (new resource)
400Bad Request
401Unauthorized
402Payment Required (no tokens)
403Forbidden
404Not Found
429Rate Limited
500Internal Server Error

​
Handling Errors in Code

​
TypeScript

interface APIError {
  error: {
    code: string;
    message: string;
    details?: Record<string, unknown>;
  };
}

async function generateMockup(params: GenerateParams) {
  const response = await fetch('https://garmint.app/api/v1/generate', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(params),
  });

  if (!response.ok) {
    const error: APIError = await response.json();
    
    switch (error.error.code) {
      case 'unauthorized':
        throw new Error('Invalid API key');
      case 'insufficient_tokens':
        throw new Error('Buy more tokens at garmint.app');
      case 'rate_limited':
        const retryAfter = response.headers.get('Retry-After');
        throw new Error(`Rate limited. Retry in ${retryAfter}s`);
      default:
        throw new Error(error.error.message);
    }
  }

  return response.json();
}

​
Python

import requests

def generate_mockup(params):
    response = requests.post(
        'https://garmint.app/api/v1/generate',
        headers={'Authorization': f'Bearer {API_KEY}'},
        json=params
    )
    
    if not response.ok:
        error = response.json()['error']
        
        if error['code'] == 'unauthorized':
            raise Exception('Invalid API key')
        elif error['code'] == 'insufficient_tokens':
            raise Exception('Buy more tokens at garmint.app')
        elif error['code'] == 'rate_limited':
            retry_after = response.headers.get('Retry-After', 60)
            raise Exception(f'Rate limited. Retry in {retry_after}s')
        else:
            raise Exception(error['message'])
    
    return response.json()

​
Debugging Tips

Ensure you’re sending:
  • Authorization: Bearer gm_live_xxx
  • Content-Type: application/json for POST requests
Design and garment URLs must be:
  • Publicly accessible (no auth required)
  • HTTPS preferred
  • Valid image formats (PNG, JPEG, WebP)
The X-Tokens-Remaining header shows your current balance in every response.
Monitor X-RateLimit-Remaining to avoid hitting limits.

​
Getting Help

If you encounter persistent errors:
  1. Check our status page
  2. Search Discord for similar issues
  3. Email api@garmint.app with:
    • Your request (redact API key)
    • The error response
    • Timestamp of the request