API error codes and how to fix themErrors
Every error has the same shape. Branch on code, which never changes. message is for people and may be reworded. Quote requestId when you contact support.
{ "code": "unknown_user_key", "message": "That user key does not exist, or has been revoked.", "requestId": "01J9F3Q0YB4V7XZ2M8K6R5T1AC"}Retry only 429 and 5xx responses. Any other error will fail the same way again.
Sending
400empty_message
message was missing or only whitespace.
Put text in message. A title alone isn't enough.
400message_too_long
message was over 1024 characters.
Shorten it and link to the rest with url. A lock screen shows two lines.
400invalid_priority
priority wasn't between -2 and 2.
Use -2, -1, 0, 1 or 2. Emergency (2) is the highest.
400emergency_needs_retry_and_expire
Priority 2 arrived without both retry and expire.
Set how often to repeat and when to stop. Neither has a default.
400retry_too_short
retry was under 30 seconds.
Raise it. Repeating every few seconds trains people to mute alerts.
400expire_too_long
expire was over 3 hours.
Lower it, and use an escalation policy to reach someone else.
400retry_exceeds_expire
retry was longer than expire, so the alert would never repeat.
Make retry shorter than expire.
400retry_requires_emergency
retry or expire arrived on a message below priority 2.
Send priority 2, or drop both fields. Acciti refuses them so you never expect a repeat that won't happen.
400dedup_window_without_key
dedupWindow arrived with no dedupKey to apply to.
Send dedupKey too, or drop the window.
400url_title_without_url
urlTitle arrived with no url to title.
Send url too, or drop the title.
400invalid_ttl
ttl was under one second.
Set it to at least one second, or leave it out.
400unknown_sound
The sending team has no sound by that name.
Check the spelling, or upload the sound on the dashboard.
400unknown_escalation
The sending team has no escalation policy by that name.
Check the policy name on the dashboard.
400unsupported_media_type
The body was not JSON.
Set Content-Type: application/json.
401unauthorized
The sender token is wrong, revoked, or missing.
Check the Authorization: Bearer header. Retrying won't help.
402plan_required
The send named an escalation policy, and the team's plan doesn't include them. The body names requiredPlan and requiredFeature.
Upgrade, or send without escalation. The message wasn't sent.
404unknown_user_key
No such recipient, or the key was rotated.
Ask the recipient for their current key. Retrying won't help.
429quota_exhausted
The team has used its monthly allowance. The error message names the reset date.
Wait for the reset or upgrade. You're never billed for overage.
429rate_limited
Too many requests in a short time.
Back off and retry. This is the one to retry.
Resolving
Finding nothing to close isn't an error. A service that recovered before anyone was alerted gets 200 with a count of zero.
400missing_dedup_key
dedupKey was missing or blank.
Send the dedupKey the alert was raised with.
400unsupported_media_type
The body was not JSON.
Set Content-Type: application/json.
401unauthorized
The sender token is wrong, revoked, or missing.
Check the Authorization: Bearer header. Only the sender that raised an alert can resolve it.
404unknown_user_key
No such recipient, or the key was rotated.
Ask the recipient for their current key. Retrying won't help.
404not_found
When resolving by message ID, this sender didn't send that message.
Check the ID. The response doesn't say whether the message exists, so a token can't probe for IDs.