Errors and Rate Limits
Handle public API errors, validation failures, and rate limiting.
Public API errors return a JSON object with an error message.
Log both the HTTP status and error message. The status tells your integration how to respond, while the message explains what Agiled rejected.
Log request method, path, status, error, request ID when available, and the external job or record ID. This makes retries and support review much faster.
Common Status Codes
| Status | Meaning |
|---|---|
400 | The request body was not valid JSON. |
401 | The request did not include a valid bearer token. |
403 | The token is valid but does not have the required ability, or the workspace plan does not allow API access. |
404 | The record, organization scope, or endpoint target was not found. |
409 | The idempotency key was reused with a different request body. |
422 | The request was understood but failed validation. |
429 | The token exceeded the public API rate limit. |
500 | The request failed unexpectedly. |
Rate Limits
Public API rate limits are tracked per token and action:
- Read requests:
60requests per minute. - Write requests:
30requests per minute.
When a request is rate limited, Agiled returns 429 and includes a
Retry-After header with the wait time in seconds.
Back off per token and action. Increasing parallel requests after a 429 will
usually make recovery slower.
Queue bulk jobs and keep concurrency low enough that normal app usage and other integrations are not starved by one import.
Retry Guidance
- Retry
429only afterRetry-After. - Retry transient
500errors with backoff. - Do not retry validation errors until the request body is corrected.
- Use idempotency keys for create/update/delete retries.
Debugging Checklist
For 401 or 403, check token, abilities, workspace, and plan access. For
404, confirm the record ID and organization scope. For 422, log validation
details and fix the payload before retrying.
Production Handling
Treat 400, 401, 403, 404, 409, and 422 as action-required unless you
know the cause is temporary. Retry only 429 and transient 500 responses with
bounded backoff.
Troubleshooting
If errors spike after a deploy, compare the request body, API key, base URL, and endpoint path against the previous working version.
Error Logging Fields
Log enough context to replay or investigate the failed operation:
- method and path
- status code and response body
- external job ID or source record ID
- idempotency key for write requests
- API key owner or integration name
- retry count and next retry time
Do not log bearer tokens, webhook secrets, payment card data, or private customer content unless your security policy explicitly allows it.
Backoff Pattern
Use bounded exponential backoff for transient failures. Stop retrying when the error is validation, permission, missing record, or idempotency conflict. Those errors need a code, mapping, permission, or data fix before another request can succeed.