Core Concepts
API Versioning
The current API version is 3.0.0 (semantic versioning).
- Base URL: https://api.gravatar.com/v3
- OpenAPI Specification: https://api.gravatar.com/v3/openapi
Email Hashing
All Gravatar requests require a proper email hash as identifier. Don’t use MD5!
Follow these steps:
- Trim leading and trailing whitespace
- Convert the entire email to lowercase
- Create a SHA256 hash of the processed email
// Correct email hashing for Gravatar
function createGravatarHash(email) {
// Process the email properly
const processedEmail = email.trim().toLowerCase();
// Create SHA256 hash
return crypto.createHash('sha256').update(processedEmail).digest('hex');
}
// Example showing the importance of proper processing
const incorrectHash = createHash('MyEmailAddress@example.com '); // With trailing space
// Returns: 'bbb8db824654275128ce09499cbbeff439840ae68f19f83861c243450dc1d6c7'
const correctHash = createGravatarHash('MyEmailAddress@example.com ');
// Returns: '84059b07d4be67b806386c0aad8070a23f18836bbaae342275dc0a83414c32ee'
OpenAPI Specifications (OAS – formerly Swagger)
Gravatar offers a machine-readable OpenAPI Specification (OAS) for version 3.0.0 of its API.
This specification provides a complete and standardized description of the Gravatar API, making it easy to explore, understand, and integrate with your own applications.
The complete API specification is available at: https://api.gravatar.com/v3/openapi
Rate Limiting
The Gravatar API is free to use, and its rate limits are customizable based on your needs. While default limits are set to prevent misuse, you can apply for much higher limits to accommodate specific usage requirements at no additional cost. Simply reach out to the Gravatar team and describe your use case and needs.
Default rate limits:
| Authentication | Requests per Hour |
| API Key | 1000 |
ℹ️ Take into account that Avatar Endpoint API requests do NOT count towards the limits mentioned above. These limits only apply to the Profiles endpoint.
Rate limit information is included in response headers:
- X-RateLimit-Limit: Total requests allowed in current period
- X-RateLimit-Remaining: Remaining requests in current period
- X-RateLimit-Reset: Unix timestamp when the limit resets
Data Formats
Profile data may be requested in different data formats for simpler programmatic access. The following formats are supported:
Error Handling & Troubleshooting
Error Response Format
All API errors follow a consistent format:
{
"error": "Error message description",
"code": "error_code"
}
Common Error Codes
| HTTP Status | Error Code | Description | Solution |
| 400 | uncropped_image | Image is not square | Crop image to 1:1 ratio before uploading |
| 400 | unsupported_image | File format not supported | Use JPG, PNG, or GIF formats |
| 401 | N/A | Authentication failed | Check API key or OAuth token |
| 403 | insufficient_scope | Token lacks permissions | Request proper scopes during OAuth |
| 404 | disabled | Profile is disabled | No solution – user has disabled profile |
| 429 | rate_limit_exceeded | Too many requests | Implement rate limiting, use exponential backoff |
| 500 | N/A | Server error | Retry with exponential backoff |
Troubleshooting Guide
Avatar Not Loading
- Verify the email hash is correct (trim whitespace, lowercase)
- Check if the user has set an avatar for this email
- Add a default parameter to display a fallback: ?d=mp
Profile Not Found
- Confirm you’re using the hash of the primary email on the account
- Many users have multiple addresses on a single account
- Avatar requests may succeed while profile requests fail for secondary emails
Rate Limiting Issues
- Implement proper caching to reduce API calls
- Add exponential backoff for retries
- Apply for increased rate limits through Developer Dashboard
Gravatar For Developers 