Guides and reference

Errors and retries

How to read a failed answer, which answers to retry, and how to retry safely.

#Read status first

#Retryable answers

#How to retry

• Honour Retry-After. A RATE_LIMITED answer (HTTP 429) carries a Retry-After header and retry_after_seconds: wait that long.
• Back off. Otherwise wait 1 s, then 2 s, then 4 s; give up after three retries and log the answer.
• Retry with the same link to the lead. Retry a result submit with the same search_lead_id, and a direct post with the icon_lead_id ICON returned. ICON then recognises an offer that already accepted the lead and answers DUPLICATE (Duplicate - Offer) instead of selling it twice.
• A DUPLICATE on a retry can mean your earlier attempt was accepted. Before you treat the lead as refused, ask your ICON contact with its icon_lead_id.
• No answer at all (a network error or your own timeout): retry once, as above. Give a submit a generous timeout (30 seconds or more): the school's system answers inside that call.
• INTERNAL_ERROR is not retryable as is. Send your ICON contact the time and the icon_lead_id (a submit's answer also carries a request_id).

#Error body

{
  "code": "REQUIRED_FIELD_MISSING",
  "status": "invalid",
  "reason": "Missing HS grad year",
  "message": "Required field missing",
  "retryable": false,
  "field": "lead.education.high_school_graduation_year"
}

{
  "code": "RATE_LIMITED",
  "status": "failed",
  "reason": "Too many requests",
  "message": "Too many requests",
  "retryable": true,
  "retry_after_seconds": 2
}