Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.snappy.com/llms.txt

Use this file to discover all available pages before exploring further.

Snappy uses standard HTTP response codes to indicate the success or failure of an API request. If a request fails, we provide a descriptive error object to help you identify and resolve the issue.

​
The Error Object

Every error response follows a consistent JSON structure: 
{  
    "status": 401,  
    "errorCode": 10001,  
    "message": "Authorization key is invalid."  
}
For validation errors (HTTP 400), the status field is replaced by path, which identifies the specific parameter that failed validation. All other error fields remain the same. 
{
  "path": "recipients[0].email",
  "errorCode": "INVALID_REQUEST",
  "message": "Invalid email format."
}
FieldDescription
statusThe HTTP status code (e.g., 400, 401, 403).
errorCodeA granular sub-code representing the specific business logic error.
messageA human-readable description of the error.
Error codes are stable; changing a code is considered a breaking change. However, error messages may be updated over time to provide better clarity. Your integration should rely on theerrorCode for programmatic handling

​
HTTP Status Codes

​
400 – Bad Request

The server could not process the request, usually due to a syntax error in the URL or the JSON body. How to fix:
  • Verify your request body matches the expected schema
  • Ensure all required fields are present (e.g. campaignId, recipient.email)
  • Check that field values are the correct type (e.g. strings vs. integers)
  • Review the errorCode in the response body.

​
401 – Unauthorized

There is an issue with your API key credentials. How to fix:
  • Missing header — ensure you are passing the X-Api-Key header on every request
  • Invalid key — double-check that the key hasn’t been mistyped or deleted from the Dashboard
  • Expired key — check whether the key has reached its expiration date and rotate it if needed. See Authentication & Security → Key Rotation

​
403 – Forbidden

Your key is valid but does not have permission to access the requested resource. How to fix:
  • Wrong scope — check that your API key was created with the correct scope for this action (e.g. gifts:create to create gifts). See Authentication & Security → Permissions
  • Wrong environment — make sure you are not using a Testing API key against a Production resource or vice versa. See Before You Begin

​
404 – Not Found

The requested resource does not exist or could not be found. How to fix:
  • Double-check the ID in your request path — copy it directly from a previous API response to avoid typos
  • Verify the resource was successfully created before attempting to retrieve or update it
In some cases Snappy returns a 404 instead of a 403 to avoid exposing the existence of resources your key doesn’t have access to. If you’re confident the resource exists, check your key’s scope and account access.

​
429 – Too Many Requests

Your integration has exceeded the standard API rate limit. How to fix:
  • Pause your requests immediately.
  • Implement an exponential backoff strategy — wait a short period before retrying, and increase the wait time with each subsequent retry.
  • Review your request frequency to ensure you stay within the standard limit of 100 requests per second. See Rate Limits.

​
500 – Internal Server Error

Something went wrong on Snappy’s end. How to fix:
  • Check the Snappy Status Page to see if there is an ongoing incident
  • If no incident is reported and the issue persists, contact support with the following details:
    • Request URL and method
    • The errorCode returned in the response body
    • A timestamp of when the error occurred

​
504 – Gateway Timeout

The request took too long to process and timed out. How to fix:
  • This is usually temporary — retry the request after a short delay
  • Implement an exponential backoff strategy in your integration to handle timeouts gracefully
  • If the issue persists on a specific endpoint, contact support with the request details
Last modified on April 30, 2026