Errors & Rate Limits - EASYCRED Documentation

Response Envelope

Every response from the EasyCred API uses a single consistent envelope:

Success
Failure
Validation Error

{
  "success": true,
  "data": { ... }
}

{
  "success": false,
  "error": "Human-readable error message"
}

{
  "success": false,
  "error": "Validation failed",
  "details": [
    { "field": "customer.pan", "message": "Invalid PAN format" },
    { "field": "customer.pinCode", "message": "Must be exactly 6 digits" }
  ]
}

On validation errors from POST /journey/initiate, the envelope also carries a field-level details array. Use it to point the customer at the exact field, and always fall back to the top-level error.

HTTP Status Codes

Code	Meaning	Common Causes
`200` / `201`	Success / Created	Request processed successfully
`400`	Validation error	Bad field value, or `ONLINE_INSTANT` sent to the journey endpoint
`401`	Authentication failed	Bad/missing signature, stale timestamp (>±300s), replayed nonce, or missing journey session
`403`	Authenticated but not allowed	Missing scope, product not granted, or key suspended/revoked
`404`	Not found	Journey or application ID does not exist
`409`	State conflict	Action sent at the wrong step, or a duplicate action in flight
`429`	Rate limit exceeded	Too many requests — see rate limits below

Rate Limits

Per-Minute Limit

120 requests / minute per API keyEvery response includes a RateLimit-Remaining header so you can track your usage.

Per-Day Limit

20,000 requests / day per API keyThese are default limits — contact EasyCred if your integration needs higher throughput.

Retry Strategy

On 429 — Rate Limit Exceeded

Back off and retry. Check the RateLimit-Remaining header and respect the Retry-After header if present. Use exponential backoff to avoid hammering the API.

On 409 — State Conflict (after an action)

Re-read journey state and re-evaluate the category — the journey has already advanced. Do not blindly retry the same action.Submitting the same action twice is safe — it is single-flight locked and a duplicate returns 409 without advancing the journey.

On 5xx — Server Error

Retry with exponential backoff. EasyCred’s infrastructure is highly available, but transient errors can occur during maintenance windows.

Error Handling Checklist

Check the success field

Always check response.success before accessing response.data.

Handle validation errors

For 400 from /journey/initiate, iterate response.details to surface field-specific messages to your user.

Never retry 403

A 403 means your key lacks permission or the product isn’t granted — retrying won’t help. Check your scopes or contact EasyCred.

Re-read state on 409

Don’t retry the same action. Call GET /journey/{journeyId} to get the current nextAction and proceed from there.

Monitor RateLimit-Remaining

Track the RateLimit-Remaining header and implement backoff before you hit 429.

​Response Envelope

​HTTP Status Codes

​Rate Limits