Error Handling & Status Codes

The API is synchronous, so errors are returned in the HTTP response with standard status codes. This page covers common codes, which ones to retry, and what to do when a request succeeds but the results are not what you expected.

Status Codes

Code	Meaning	Typical cause	What to do
`200`	Success	Request processed	Read the response body
`201`	Created	Campaign settings created	Read the acknowledgement and retain your `campaignId`; use Get Campaign Setting Details when you need the stored rules
`400`	Bad Request	Malformed body, missing required field, invalid parameter value, unknown Receipt Validation `campaignId`, or an operation-specific unavailable feature such as Campaign Validation on Campaign Settings	Fix the request or enable the required account feature — do not retry unchanged
`401`	Unauthorized	Missing `apikey` header	Add the key; see Quick Start
`403`	Forbidden	Invalid API key	Check the key and account association
`404`	Not Found	A defined resource-management operation could not find its resource — for example, campaign settings requested for an unknown `campaignId`	Check the identifier and the endpoint-specific contract. Unknown Receipt Validation campaigns use the operation-specific `400` contract instead
`413`	Request Entity Too Large	Complete HTTP request body exceeds 20 MiB (20,971,520 bytes)	Reduce the multipart file or encoded payload; framing and JSON/base64 expansion count toward the limit
`415`	Unsupported Media Type	The request media type was not accepted by this operation	Check the operation-specific content type and request encoding
`429`	Too Many Requests	Rate limit exceeded	Retry with exponential backoff; see Usage Limits
`500`	Internal Server Error	Unexpected error on Taggun's side	Retry with backoff only when retrying is safe for that operation; otherwise reconcile the outcome first
`502`	Bad Gateway	Transient upstream/processing error	Retry with backoff only when retrying is safe for that operation; otherwise reconcile the outcome first

Error Response Format

Application errors generally use the standard Hapi Boom JSON envelope below. Some handlers may add properties, so treat these three fields as the common application-error contract rather than an exhaustive object:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Description of what was wrong with the request"
}

API-gateway authentication and rate-limit failures are exceptions. A missing apikey returns 401 with { "message": "No API key found in request" }; an invalid key returns 403 with { "message": "Invalid authentication credentials" }; and the observed 429 response was { "message": "API rate limit exceeded" } without Retry-After.

Feature availability is operation-specific rather than a universal 403 rule. With a valid key and Campaign Validation disabled, Campaign Settings list/get/update/delete returned 400 Boom with { "statusCode": 400, "error": "Bad Request", "message": "Please contact Taggun for the feature Campaign Validation" }. Do not infer the same status or message for unrelated features or operations.

Campaign Settings Update and Delete use a separate acknowledgement/not-found family with result and statusCode:

{
  "result": "Campaign ID not found - coffee-june-2026",
  "statusCode": 404
}

Use the endpoint's documented response schema rather than assuming every 400 or 404 uses Boom. Exact messages are examples for the documented branch, not constants shared by every error.

Retrying Safely

Use retries for transient failures, not for validation errors:

Retry with exponential backoff: 429; retry 500, 502, and network-level failures only when retrying is safe for that operation.
Do not retry unchanged: 400, 401, 403, 404, 413, 415 — these fail the same way every time until the request, credentials, account access, or request size is fixed.
Before resubmitting a rejected file, check the file type, file size, and image dimensions.

A timeout, connection reset, 500, or 502 on a state-changing or billable request can leave the outcome unknown. Do not assume Taggun operations are idempotent. For campaign or account-list operations, reconcile with GET, list, or export where available before replaying. If no read-back operation can establish the outcome, contact support before retrying.

Troubleshooting Unexpected Output

A 200 response can still be sparse or differ from what your integration expected. Work through this checklist without assuming one universal cause:

Confirm the endpoint. Simple extraction intentionally returns fewer fields than verbose extraction; validation and export operations have different response shapes.
Check enabled settings and campaign rules. Optional entities and feature envelopes appear only when the relevant capability is enabled and applicable.
Check request hints. Incorrect language, near, ignoreMerchantName, or feature-specific input can reduce or change the output.
Check document variation and image quality. Merchant layout, country, document content, blur, glare, cropping, and resolution can all affect detected data. See Performance & Response Times.
Review the response and escalate persistent misses. See Understanding Your Results. Follow Contacting Support and include your account email, the sample when safe to share, the returned trackingId, and a clear description of the issue.

Need something not covered here? Contact [email protected] — see Contacting Support.