Pag-paginate, idempotency, at paghawak ng error

Gumagamit ang Ody API ng opaque cursor pagination sa mga list endpoint nito, isang Idempotency-Key header para sa ligtas na pag-ulit ng pagpapadala ng mensahe, at isang pare-parehong error envelope na may request ID sa bawat tugon — sakop ng gabay na ito ang lahat ng tatlo.

Pag-paginate gamit ang Cursor

Ang GET /v1/api/contacts at GET /v1/api/conversations ay nagpa-paginate gamit ang ?limit= at ?cursor=:

curl "https://api.ody.co/v1/api/contacts?limit=100" \
  -H "Authorization: Bearer ody_live_…"

Kasama sa tugon ang isang nextCursor — ipasa ito pabalik bilang ?cursor= upang kunin ang susunod na pahina, at huminto kapag ito ay null:

{ "contacts": [ … ], "nextCursor": "eyJ…" }

• Ang mga cursor ay opaque — palaging ipasa ang mga ito nang eksakto; ang isang binago o luma na cursor ay nagbabalik ng 400 invalid_argument.
• Mga limitasyon sa laki ng pahina: ang mga contact ay default 50, max 200; ang mga conversation ay default 50, max 100. Ang GET /v1/api/messages/search (default 25, max 100) at GET /v1/api/calls (default 50, max 200) ay tumatanggap lamang ng ?limit=, nang walang mga cursor.
• Sinusundan ng mga opisyal na SDK ang nextCursor para sa iyo gamit ang listAll() / list_all() — tingnan ang SDK quickstart: TypeScript at Python.

Idempotent na Pagpapadala ng Mensahe

Ang isang pagkabigo sa network pagkatapos mong POST /v1/api/messages ay nag-iiwan sa iyo na hindi alam kung lumabas ang text — ang bulag na pag-ulit ay nagpapataas ng panganib ng dobleng pagpapadala. Magpadala ng Idempotency-Key header (anumang string hanggang 200 character, natatangi sa bawat lohikal na pagpapadala) at magiging ligtas ang mga pag-ulit:

curl https://api.ody.co/v1/api/messages \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{"to":"+15125550123","body":"Your order shipped!"}'

• Ang unang matagumpay na tugon ay iniimbak sa loob ng 24 na oras; anumang pag-ulit na may parehong key sa loob ng panahong iyon ay irereplay ito nang eksakto sa halip na magpadala muli, na may Idempotency-Replayed: true response header.
• Kunin ang key mula sa iyong sariling business event ("order-1042-shipped"), hindi isang random na halaga sa bawat pagtatangka — ang buong punto ay ibahagi ito ng mga pag-ulit.

Ang Error Envelope

Ang bawat error response ay gumagamit ng parehong hugis:

{ "error": { "code": "permission_denied", "message": "This API key is missing the 'messages:send' scope", "requestId": "req_…" } }

Status	Code	Ano ang gagawin
400	invalid_argument	Ayusin ang kahilingan — sinasabi ng mensahe kung ano ang mali
401	unauthenticated	Ang key ay nawawala, invalid, o binawi. Huwag ulitin; alertuhan ang may-ari ng integrasyon
403	permission_denied	Pinangalanan ng mensahe ang nawawalang scope — gumawa ng key na mayroon nito
404	not_found	Hindi umiiral ang resource sa workspace na ito
409	failed_precondition	Hindi pa magagawa ito ng workspace (hal. walang aktibong numero na mapagpapadalhan). Ilabas ito, huwag ulitin
429	resource_exhausted	Na-rate limit — maghintay ng Retry-After segundo, pagkatapos ay ulitin na may backoff
500	internal	Ulitin na may exponential backoff at jitter; limitahan ang mga pag-ulit

Mga Request ID

Ang bawat tugon — tagumpay o error — ay nagdadala ng X-Request-Id header, na inuulit bilang requestId sa mga error body. I-log ito kasama ng iyong sariling mga request log, at banggitin ito kapag nakikipag-ugnayan ka sa suporta: itinuturo nito ang eksaktong kahilingan sa aming panig. Maaari mo ring ibigay ang iyong sariling X-Request-Id (hanggang 64 na character, mga letra/digit/_/-) at uulitin ito ng Ody, na nagpapadali sa pag-uugnay ng mga pag-ulit.

Mga Kaugnay na Artikulo

• Pangkalahatang-ideya ng API at pagpapatunay
• Mga limitasyon sa rate ng API at pinakamahuhusay na kasanayan
• SDK quickstart: TypeScript at Python