Help Center / Developers & API6 min read
Errors, limits and troubleshooting
Every error status the API returns, every limit in one table, and what to check when an action, a webhook or pushed knowledge is not working.
Error responses
Every error has a JSON body with one sentence saying what went wrong:
{ "error": "url must be a public https address." }
| Status | Meaning |
|---|---|
| 400 | The request is invalid: a missing field, a wrong type, a bad name. The message says which. |
| 401 | The API key is missing, malformed or revoked, or the access token has expired or was revoked. |
| 403 | The business's plan does not include the API, its account is not active, or a plan limit is reached (for example knowledge sources). |
| 404 | The action, intake, endpoint or knowledge key does not exist for this business, or another key or app made it. |
| 413 | Knowledge content is longer than 8,000 characters. |
| 429 | Too many requests of this kind; try again later. |
| 500 | Something failed on Ordina's side. Retry with a short backoff. |
| 503 | Ordina could not check which key or app owns an item just now, or intakes are not available yet. Nothing was changed; retry after the Retry-After seconds. |
Limits
| What | Limit |
|---|---|
| API keys per business | 10 active |
| Webhook endpoints per business | 20 |
| Webhook answer time | 10 seconds; retried 5 more times over about 15 hours, by a job that runs every 15 minutes |
| Connected actions per business | 10 |
| Action parameters | 8, flat: string, number, integer, boolean |
| Action description | 20 to 600 characters |
| Action answer time | 5 seconds for a lookup, 10 seconds for a write |
| Action response | 16 KB read; first 4,000 characters reach the Secretary |
| Lookups per customer message | 2 |
| Write requests per customer message | 1, shown to the customer for a yes |
| Lookups per phone call | 6 (write actions do not run on calls) |
| A write request waits for a yes | 30 minutes; a yes within 1.5 seconds of it being shown is asked again |
| Intakes per business | 5 |
| Intake questions | 1 to 12, at least one required; a select has 2 to 20 options |
| Intake description | 20 to 500 characters |
| Intake responses | 50 per page |
| Knowledge content | 20 to 8,000 characters per key |
| Knowledge sources | 5 on Business, including PDFs and websites |
| Knowledge pushes | 120 per hour per business |
| List endpoints | Up to 100 items per request |
The Secretary never calls my action
- Is it switched on?
GET /api/v1/actions/{id}showsenabled. Only the owner can switch it on. - Did you change it? Any change through the API switches it off until the owner approves it again.
- Was your key revoked, or your app disconnected? That switches off every action it registered.
- Does the description match how customers ask? If customers say "parcel" and your description only says "shipment", add both. The description is all the Secretary sees.
- Is a required parameter something customers rarely say? The Secretary asks for a missing required value instead of calling. Make it optional if you can answer without it.
- Was the message just a name, a phone number or a yes? Lookups are not considered on routine replies like those. Write actions still are, because such a reply can be the detail a request was waiting for.
The Secretary says it could not check
Look at the call history (GET /api/v1/actions/{id}):
| Status | Likely cause |
|---|---|
| timeout | Your endpoint took over 5 seconds. Watch for cold starts. |
| error, HTTP 4xx or 5xx | Your endpoint refused or failed. A 401 or 403 often means signature verification is rejecting good requests: see Verify signatures. |
| error, did not return JSON | An HTML error page, or an empty body. |
| error, larger than 16000 bytes | Trim the response. |
| error, address cannot be fetched | Your hostname resolves to a private address. |
| rejected | The Secretary's values did not fit your schema, or a write could no longer run as confirmed (for example the action changed after the request was shown). Not your endpoint's fault; check enum values and types. |
| unknown | A write got no answer within 10 seconds, or the connection dropped. Ordina does not retry it; look up its Idempotency-Key in your logs to see whether it went through. |
Webhooks are not arriving
- Check the endpoint is enabled and see its history in Integration, Webhooks, or press Test to send a
ping. - Answer 2xx within 10 seconds, without a redirect. A trailing-slash redirect counts as a failure.
- Make sure your firewall accepts requests from the internet.
Pushed knowledge is not used
GET /api/v1/knowledgeconfirms it is stored.- The question has to be one the text actually answers. Put the key facts early in the text, in plain sentences.
- Too much text in total means some is not read for a given answer. Shorter, focused keys work best.
Still stuck
Email help@useordina.com with the business handle, the action name or endpoint, and the time of the request. The call id (X-Ordina-Call) or delivery id (X-Ordina-Delivery) helps us find it quickly.
Did this answer it?If not, write to help@useordina.com with your handle, or contact us. A person replies.
Contact us 