For developers
API errors
Every error answers JSON with a code in detail, like {"detail": "auth.unauthorized"}. A few codes add fields beside it.
| Status | Code | Meaning | Also returned |
|---|---|---|---|
| 400 | assess.unsupportedLanguage | language (or source_language or target_language) is not one of the API’s language codes, spelled exactly. | — |
| 400 | request.bodyNotJson | The JSON body could not be read as JSON. | — |
| 400 | request.unknownAudioFormat | audio_format is neither mp3 nor wav. | — |
| 400 | assess.noAudio | The audio file is empty. | — |
| 400 | assessment.audioUnreadable | The uploaded file is not audio Spelly can read. | — |
| 401 | auth.unauthorized | The X-API-Key header is missing, wrong or revoked. | — |
| 401 | widget.keyInvalid | The widget key is unknown or revoked. | — |
| 402 | operator.trialExhausted | Your units are used up. | remaining and requested (units), upgrade_url (null while plans are not sold) |
| 403 | auth.endpointNotAllowed | Your key may not call this route; the routes it may call are under All endpoints. | — |
| 403 | operator.inactive | The account that owns the key is paused or deleted. | — |
| 404 | request.notFound | There is no such route. | — |
| 405 | request.methodNotAllowed | The route exists, but not with this method. | — |
| 413 | assess.recordingTooLong | The recording is over the size limit. | — |
| 413 | request.tooLarge | The request body is too large. | — |
| 422 | assessment.nothingHeard | The recording holds no speech: it is silent, or the microphone picked up nothing. Nothing is charged. | — |
| 422 | request.invalid | A field is missing, is one the call does not take, or has a value it does not take; or the body is not a JSON object. | errors: one {"field", "problem"} per wrong field, with a value for some problems; problem is a type such as missing, extra_forbidden (a field the call does not take), string_too_long, no_letters (a text with no letters to read), dict_type (the body is not a JSON object), unknown_sound or literal_error |
| 429 | request.tooManyRequests | Too many requests: from your address (see Rate limits), or over your key’s own per-minute limit when one is set. | Header Retry-After: seconds to wait |
| 500 | server.failed | Something failed on Spelly’s side. | — |
| 503 | service.busy | Spelly is busy: requests are waiting their turn. | Header Retry-After: seconds to wait |
| 503 | service.unavailable | Spelly’s scoring and voice service is not answering right now. Spelly’s status says whether it is down. | Header Retry-After: seconds to wait |
| 503 | service.maintenance | Spelly is being updated, usually for a minute or two. Every call is refused until it is back, so nothing is half done. Spelly’s status shows it too. | Header Retry-After: seconds to wait |