Skip to main content

​
Response Codes

Legitmark uses standard HTTP codes to indicate the success or failure of your requests. In general, 2xx HTTP codes correspond to success, 4xx codes are for user-related failures, and 5xx codes are for infrastructure issues.
StatusDescription
200Successful request.
201Resource created successfully.
204Successful request with no content.
400Check that the parameters were correct.
401The API key used was missing or authentication required.
403The API key used was invalid or insufficient permissions.
404The resource was not found.
409Conflict - duplicate resource or constraint violation.
429The rate limit was exceeded.
500Internal server error.
501Not implemented.
5xxIndicates an error with Legitmark servers.
Check Error Codes for a comprehensive breakdown of all possible API errors.

​
Error Response Format

All error responses follow this structure: 
{
  "success": false,
  "error": {
    "code": 400,
    "timestamp": "2024-01-01T00:00:00.000Z",
    "message": "User-friendly error message",
    "errors": [
      {
        "code": "validation/missing-field",
        "message": "field_name is required."
      }
    ]
  }
}

​
Error Categories

​
Validation Errors (400)

Validation errors occur when request parameters don’t meet requirements: 
{
  "success": false,
  "error": {
    "code": 400,
    "timestamp": "2024-01-01T00:00:00.000Z",
    "message": "Validation failed",
    "errors": [
      {
        "code": "validation/missing-user_id",
        "message": "user_id is required."
      },
      {
        "code": "validation/invalid-email",
        "message": "Invalid email address format."
      }
    ]
  }
}

​
Authentication Errors (401)

Authentication errors occur when API key is missing or invalid: 
{
  "success": false,
  "error": {
    "code": 401,
    "timestamp": "2024-01-01T00:00:00.000Z",
    "message": "Authentication required",
    "details": "authorization/missing_token"
  }
}

​
Authorization Errors (403)

Authorization errors occur when API key lacks required permissions: 
{
  "success": false,
  "error": {
    "code": 403,
    "timestamp": "2024-01-01T00:00:00.000Z",
    "message": "Insufficient permissions",
    "details": "authorization/insufficient_permissions"
  }
}

​
Not Found Errors (404)

Not found errors occur when requested resource doesn’t exist: 
{
  "success": false,
  "error": {
    "code": 404,
    "timestamp": "2024-01-01T00:00:00.000Z",
    "message": "Resource not found",
    "details": "error/resource_not_found"
  }
}

​
Conflict Errors (409)

Conflict errors occur when creating duplicate resources or constraint violations: 
{
  "success": false,
  "error": {
    "code": 409,
    "timestamp": "2024-01-01T00:00:00.000Z",
    "message": "Resource already exists",
    "details": "error/duplicate_resource"
  }
}

​
Server Errors (5xx)

Server errors indicate issues with Legitmark infrastructure: 
{
  "success": false,
  "error": {
    "code": 500,
    "timestamp": "2024-01-01T00:00:00.000Z",
    "message": "Internal server error",
    "details": "error/internal_server_error"
  }
}

​
Troubleshooting

​
Common Issues

400 Bad Request
  • Check that all required parameters are included
  • Verify parameter types and formats
  • Ensure JSON is properly formatted
  • Check field naming uses snake_case
401 Unauthorized
  • Verify API key is included in Authorization header
  • Check API key format: Bearer leo_xxxxxxxxx
  • Ensure API key is active and not expired
403 Forbidden
  • Verify API key has required permissions
  • Check if resource access is restricted
  • Contact support for permission issues
404 Not Found
  • Verify resource ID/UUID is correct
  • Check if resource exists
  • Ensure endpoint URL is correct
429 Rate Limited
  • Wait before retrying (check retry-after header)
  • Implement exponential backoff
  • Consider upgrading rate limits
500 Server Error
  • Retry request after a brief delay
  • Check Legitmark status page
  • Contact support if issue persists

​
Debugging Tips

  1. Check Response Headers
    • Content-Type should be application/json
    • Rate limit headers show current usage
    • Request ID for support inquiries
  2. Validate Request Format
    • Use proper Content-Type header
    • Ensure JSON syntax is valid
    • Verify all required fields are included
  3. Test with Minimal Data
    • Start with simplest possible request
    • Add complexity incrementally
    • Use API playground for testing
  4. Monitor Rate Limits
    • Track API usage patterns
    • Implement proper retry logic
    • Cache responses when appropriate