Error Handling

Error Response Structure

When a request fails, the API returns an HTTP 401 or 422 with a code and a message.

{
  "code": 102,
  "message": "Invalid results_endpoint"
}

Error Object Fields

Field	Type	Description
code	integer	Numeric error code identifying the problem
message	string	Human-readable description of the error

---

Error Code Reference

Authentication

Code	HTTP	Message	Description
101	422	Invalid api_key	The api-key header is missing or does not match an active key
9	401	Client is unknown	The credentials supplied could not be resolved to a client
7	401	No client configuration found	No configuration exists for your account. POST one before creating jobs

Configuration

Returned by POST /ereceipts/config.

Code	HTTP	Message	Description
102	422	Invalid results_endpoint	The results_endpoint value is not a valid URL
104	422	Both global day_cutoff and date_cutoff specified	You provided both at the top level; use only one
105	422	Neither global day_cutoff nor date_cutoff specified	You must provide either day_cutoff or date_cutoff at the top level
106	422	Global day_cutoff is not an integer	day_cutoff must be a positive whole number
107	422	Global date_cutoff is not an integer	date_cutoff must be a positive whole number (UNIX seconds)
103	422	One or more retailers missing emails key	A retailer object is missing the required email field
127	422	One or more retailers contains an email that is not a valid email address or domain	A retailer email is neither an email address nor a bare domain
108	422	One or more retailers contains both day_cutoff and date_cutoff	A retailer specifies both cutoff types; use only one per retailer
109	422	One or more retailers contains a day_cutoff that is not an integer	A retailer's day_cutoff must be a positive whole number
110	422	One or more retailers contains a date_cutoff that is not a valid integer	A retailer's date_cutoff must be a positive whole number (UNIX seconds)
8	422	retailers must be an array	The retailers field was supplied as something other than an array
128	422	Failed to save client configuration	The configuration could not be written. Retry the request

Retailers

Returned by DELETE /ereceipts/retailers.

Code	HTTP	Message	Description
111	422	No retailers specified	retailer_emails was missing, not an array, or empty

Jobs

Returned by POST /ereceipts/create_job.

Code	HTTP	Message	Description
118	422	You must specify either an email_hash or a client_user_id	Neither identifier was provided
13	422	Existing job in progress	A job for this user is already queued or executing
5	422	Invalid credentials	The mailbox credentials were malformed, or the provider rejected them
6	422	Expired OAuth token	The OAuth token has expired and must be refreshed
8	422	Bad input	The request was missing a required field, or could not be processed
999	422	Unknown error	The job could not be queued

Job Status

Returned by GET /ereceipts/status.

Code	HTTP	Message	Description
119	401	No job_id present	The job_id query parameter is missing
120	401	job_id not found	No job with that ID exists for your account

History

Returned by POST /ereceipts/clear_history.

Code	HTTP	Message	Description
121	422	You must specify either an email_address or a client_user_id	Neither identifier was provided
117	422	Could not find specified account	No stored data matched the identifier supplied

---

Handling Common Errors

101 — Invalid API Key

Verify that the api-key header is present in every request and matches the key issued to your account. API keys are case-sensitive.

curl -X GET https://api.blinkreceipt.com/ereceipts/config \
  -H "api-key: YOUR_CORRECT_API_KEY"

102 — Invalid results_endpoint

The webhook URL must be a valid HTTPS URL that is publicly reachable. Ensure the URL does not point to localhost or a private network address in production.

{
  "results_endpoint": "https://your-server.com/webhooks/ereceipts"
}

104 / 105 — Cutoff Configuration

You must supply exactly one of day_cutoff or date_cutoff at the global level, not both and not neither. Because a POST replaces your whole configuration, this applies to every request — not only the first.

{
  "results_endpoint": "https://your-server.com/webhooks/ereceipts",
  "day_cutoff": 14
}

107 / 110 — Cutoff Format

date_cutoff is a UNIX timestamp in seconds. A millisecond timestamp is a common cause of an unexpected cutoff.

7 — No Client Configuration

POST /ereceipts/config before creating jobs. This error also appears on GET /ereceipts/config when nothing has been configured yet.

13 — Existing Job In Progress

Only one job may be in flight per user at a time. Poll GET /ereceipts/status until the current job reports completed or error, then retry.

---

Job Failures

Errors that occur while a job is processing are not returned by the API request that created it. They are reported in the job_status object from GET /ereceipts/status, in the error_code and error_message fields.

{
  "success": true,
  "job_status": {
    "id": 98765,
    "status": "error",
    "error_code": 16,
    "error_message": "IMAP connection error"
  }
}

These codes are separate from the request errors listed above. For the full list of job status values, see endpoints.md.