Core Concepts
Errors
Errors use standard HTTP statuses and one JSON envelope.
Successful responses wrap their result in data. Every error returns the same envelope, with a stable code to branch on and a readable message. For invalid input, the message starts with the field at fault.
{
"error": {
"code": "invalid_request",
"message": "scheduledFor: must be an ISO 8601 datetime"
}
}| Status | Code | Meaning | Retry? |
|---|---|---|---|
400 | invalid_request | A field, query parameter or header is missing or invalid. The message names the field. | No. Fix the request first. |
401 | unauthorized | No credential, or the key is invalid, expired or revoked. | No. Check the Authorization header. |
402 | payment_required | The workspace doesn't have enough credits for the post or comment. A post costs 32 credits and a comment 8. | Yes, after topping up. The message includes the link. |
403 | forbidden | The credential is valid but lacks the scope, or cannot reach the workspace. | No. Add the scope or link the workspace to the key. |
404 | not_found | Nothing with that ID exists in the workspace. | No. |
409 | conflict | The request clashes with the content's state, such as editing content that is about to go live. | No. Read the content again to see where it stands. |
429 | rate_limited | More than 120 requests in the last minute. | Yes, after the Retry-After header's seconds. |
500 | internal_error | Something went wrong on our side. | Yes, with backoff. |
503 | service_unavailable | The API or a service it needs is briefly unavailable. | Yes, with backoff. |
Branch on code, Not message
Messages may be reworded to be clearer. Codes and statuses stay the same within a version.
