Request errors
General errors
Authentication, scopes, unknown ids, idempotency and rate limits, in every operation.
link: https://developers.heru.app/errors/general
Any operation can answer these. They say nothing about your data: fix the request, the token or the timing, and send it again.
{
"code": "INSUFFICIENT_SCOPE",
"status": 403,
"message": "This operation needs the invoices:write scope. Ask your account team to add it to your credential.",
"link": "https://developers.heru.app/errors/general",
"request_id": "req_01m4ra8x59ehp870crwjcypejt"
}| Status | Code | What happened | What to do |
|---|---|---|---|
| 400 | MALFORMED_REQUEST | The body is not valid JSON, or not the multipart the operation expects. | Fix the body. Do not retry it unchanged. |
| 400 | IDEMPOTENCY_KEY_REQUIRED | A POST that requires Idempotency-Key came without it. | Send a key unique per operation. See idempotency. |
| 401 | UNAUTHORIZED | The Authorization header is missing, or the token is not valid. | Request a token at /oauth/token and send it as Bearer. |
| 401 | TOKEN_EXPIRED | The token is older than one hour. | Request a new token and retry once. |
| 403 | INSUFFICIENT_SCOPE | Your credential lacks the scope the operation needs. Every operation names its scope in the reference. | Ask your account team to add the scope. |
| 404 | NOT_FOUND | No resource with this id for your credentials. A resource of another company also answers 404. | Check the id and the credential. |
| 409 | IDEMPOTENCY_KEY_REUSED | The key was used in the last 24 hours with a different body or endpoint. | Use a new key for a new operation. |
| 413 | PAYLOAD_TOO_LARGE | The body is larger than the operation accepts, e.g. a signature PDF over 10 MB. | Send a smaller file. |
| 429 | RATE_LIMITED | Too many requests for your credential. | Wait the seconds in Retry-After, then retry. |
| 500 | INTERNAL_ERROR | Something failed on our side. | Retry with the same Idempotency-Key and backoff. Quote the request_id if it persists. |