Skip to main content
ParseTx uses standard HTTP response codes for top-level failures and a per-item status field for granular failures within a batch. Understanding the difference between these two layers is essential for building a robust integration — a 200 OK envelope does not always mean every transaction was successfully enriched.

​
HTTP Error Codes

When a request itself cannot be processed, ParseTx returns a non-2xx status code with a structured JSON error body. These errors affect the entire request and occur before any transactions are enriched.
CodeNameMeaningResolution
400Bad RequestInvalid JSON or a schema violation — most commonly submitting more than 10 items on the synchronous endpoint.Fix the request payload and retry.
401UnauthorizedThe X-API-Key header is missing, empty, or contains an invalid or revoked key.Verify your key in the dashboard and re-authenticate.
429Too Many RequestsYour monthly transaction quota or daily token budget has been exceeded.Wait for your quota to reset, or contact support to raise limits.
500Server ErrorAn unexpected internal error occurred on ParseTx’s infrastructure.Wait briefly and retry with exponential backoff. Contact support if it persists.

​
401 — Authentication Errors

There are two distinct 401 scenarios, each with its own response body: 
{
  "error": "Missing API key. Provide your key via the X-API-Key header."
}
Check that your requests include the X-API-Key header and that the key is copied in full from your dashboard. Keys that have been revoked (e.g., after a cancellation) will return the second response.

​
429 — Quota Errors

ParseTx enforces two independent limits that each produce a 429: Monthly transaction quota exceeded: 
{
  "error": "Monthly quota exceeded.",
  "usage": 49990,
  "limit": 50000,
  "plan": "pay_as_you_go"
}
Daily token budget exceeded: 
{
  "error": "Daily token budget exceeded. Your quota resets at midnight UTC.",
  "token_usage": 999900,
  "token_limit": 1000000,
  "plan": "pay_as_you_go"
}
The usage, limit, and token_usage fields in the response body let you programmatically detect how close you are to each threshold. The daily token budget resets at midnight UTC. Contact support if you need higher limits for high-volume use cases.

​
Partial Batch Failures

Because ParseTx processes transactions individually within a batch, a single problem item does not cause the entire request to fail. Instead:
  • The overall HTTP status is still 200 OK.
  • The envelope status field changes from "complete" to "partial".
  • Each item in the results array carries its own status field indicating whether it was resolved, should be retried, or was permanently rejected.

​
Per-Item Status Values

Item StatusMeaningShould you retry?
completeSuccessfully enriched.No — result is ready to use.
retryA transient LLM timeout occurred during inference. The item was not enriched.Yes — safe to retry with exponential backoff.
rejectedThe input was flagged as high-entropy garbage (e.g., random alphanumeric strings, pure numeric sequences) and was discarded before reaching the AI engine.No — retrying the same input will produce the same rejection.
Never retry rejected items. They have already been evaluated and discarded by the sanitization pipeline. Retrying them wastes API quota and will not produce a meaningful enrichment result.

​
Example: Partial Batch Response

{
  "results": [
    {
      "input": "NETFLIX.COM ON DEMAND",
      "status": "complete",
      "source": "cache",
      "merchant": "Netflix",
      "domain": "netflix.com",
      "category": "Entertainment",
      "mcc_code": "4899",
      "is_subscription": true,
      "confidence": 1
    },
    {
      "input": "UBER * EATS PENDING",
      "status": "retry",
      "reason": "LLM inference timed out. Retry this item."
    },
    {
      "input": "123456789012345",
      "status": "rejected",
      "reason": "Input rejected: too short, high-entropy garbage, or all PII after sanitization",
      "confidence": 0
    }
  ],
  "job_id": null,
  "status": "partial"
}

​
Handling Item Statuses in Code

After receiving a batch response, filter results by status to route each item appropriately. 
const response = await parseTxClient.enrich(transactions);

// Items to re-submit in a follow-up request
const toRetry = response.results
  .filter(r => r.status === 'retry')
  .map(r => r.input);

// Items that were permanently discarded — do not retry
const rejected = response.results
  .filter(r => r.status === 'rejected');
// Don't retry these — they were flagged as garbage input

// Successfully enriched items
const enriched = response.results
  .filter(r => r.status === 'complete');

​
Retry Strategy

For items with status: "retry", apply exponential backoff before re-submitting:
1

Collect retry candidates

After receiving a partial response, extract the input values from all retry items into a new array.
2

Wait before retrying

Start with a 1–2 second delay and double it on each subsequent attempt. This avoids hammering the API during a transient LLM outage.
3

Re-submit as a new batch

POST the retry array as a fresh request. There is no special retry endpoint — just call /v1/enrich or /v1/enrich/async again with the subset.
4

Cap your attempts

After 3–5 retry attempts, treat the remaining retry items as unresolvable for this cycle and surface them in your own error logging. Persistent retry responses may indicate an ongoing LLM infrastructure issue; check the ParseTx status page for incident reports.
Both the Node.js and Python SDKs handle exponential backoff automatically for async jobs via client.pollJob(jobId). For synchronous retries, you will need to implement your own backoff loop as shown above.